mirrors/gcc
1
0
Fork 0
mirror of https://gcc.gnu.org/git/gcc.git synced 2024-11-23 02:44:18 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Revert "sphinx: remove texinfo files"

Browse Source 
This reverts commit 54ca4eef58.
This commit is contained in:
Martin Liska 2022-11-13 21:59:29 +01:00
parent 40a3938106
commit d77de73829
77 changed files with 177510 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

853
gcc/d/gdc.texi Normal file
View File

@ -0,0 +1,853 @@
\input texinfo @c -*-texinfo-*-
@setfilename gdc.info
@settitle The GNU D Compiler
@c Merge the standard indexes into a single one.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@include gcc-common.texi
@c Copyright years for this manual.
@set copyrights-d 2006-2022
@copying
@c man begin COPYRIGHT
Copyright @copyright{} @value{copyrights-d} 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 no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the
@c man end
section entitled ``GNU Free Documentation License''.
@ignore
@c man begin COPYRIGHT
man page gfdl(7).
@c man end
@end ignore
@end copying
@ifinfo
@format
@dircategory Software development
@direntry
* gdc: (gdc). A GCC-based compiler for the D language
@end direntry
@end format
@insertcopying
@end ifinfo
@titlepage
@title The GNU D Compiler
@versionsubtitle
@author David Friedman, Iain Buclaw
@page
@vskip 0pt plus 1filll
Published by the Free Software Foundation @*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301, USA@*
@sp 1
@insertcopying
@end titlepage
@contents
@page
@node Top
@top Introduction
This manual describes how to use @command{gdc}, the GNU compiler for
the D programming language. This manual is specifically about
@command{gdc}. For more information about the D programming
language in general, including language specifications and standard
package documentation, see @uref{https://dlang.org/}.
@menu
* Copying:: The GNU General Public License.
* GNU Free Documentation License::
How you can share and copy this manual.
* Invoking gdc:: How to run gdc.
* Index:: Index.
@end menu
@include gpl_v3.texi
@include fdl.texi
@node Invoking gdc
@chapter Invoking gdc
@c man title gdc A GCC-based compiler for the D language
@ignore
@c man begin SYNOPSIS gdc
gdc [@option{-c}|@option{-S}] [@option{-g}] [@option{-pg}]
[@option{-O}@var{level}] [@option{-W}@var{warn}@dots{}]
[@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
[@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
[@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
Only the most useful options are listed here; see below for the
remainder.
@c man end
@c man begin SEEALSO
gpl(7), gfdl(7), fsf-funding(7), gcc(1)
and the Info entries for @file{gdc} and @file{gcc}.
@c man end
@end ignore
@c man begin DESCRIPTION gdc
The @command{gdc} command is the GNU compiler for the D language and
supports many of the same options as @command{gcc}. @xref{Option Summary, ,
Option Summary, gcc, Using the GNU Compiler Collection (GCC)}.
This manual only documents the options specific to @command{gdc}.
@c man end
@menu
* Input and Output files:: Controlling the kind of output:
an executable, object files, assembler files,
* Runtime Options:: Options controlling runtime behavior
* Directory Options:: Where to find module files
* Code Generation:: Options controlling the output of gdc
* Warnings:: Options controlling warnings specific to gdc
* Linking:: Options influencing the linking step
* Developer Options:: Options useful for developers of gdc
@end menu
@c man begin OPTIONS
@node Input and Output files
@section Input and Output files
@cindex suffixes for D source
@cindex D source file suffixes
For any given input file, the file name suffix determines what kind of
compilation is done. The following kinds of input file names are supported:
@table @gcctabopt
@item @var{file}.d
D source files.
@item @var{file}.dd
Ddoc source files.
@item @var{file}.di
D interface files.
@end table
You can specify more than one input file on the @command{gdc} command line,
each being compiled separately in the compilation process. If you specify a
@code{-o @var{file}} option, all the input files are compiled together,
producing a single output file, named @var{file}. This is allowed even
when using @code{-S} or @code{-c}.
@cindex D interface files.
A D interface file contains only what an import of the module needs,
rather than the whole implementation of that module. They can be created
by @command{gdc} from a D source file by using the @code{-H} option.
When the compiler resolves an import declaration, it searches for matching
@file{.di} files first, then for @file{.d}.
@cindex Ddoc source files.
A Ddoc source file contains code in the D macro processor language. It is
primarily designed for use in producing user documentation from embedded
comments, with a slight affinity towards HTML generation. If a @file{.d}
source file starts with the string @code{Ddoc} then it is treated as general
purpose documentation, not as a D source file.
@node Runtime Options
@section Runtime Options
@cindex options, runtime
These options affect the runtime behavior of programs compiled with
@command{gdc}.
@table @gcctabopt
@item -fall-instantiations
@cindex @option{-fall-instantiations}
@cindex @option{-fno-all-instantiations}
Generate code for all template instantiations. The default template emission
strategy is to not generate code for declarations that were either
instantiated speculatively, such as from @code{__traits(compiles, ...)}, or
that come from an imported module not being compiled.
@item -fno-assert
@cindex @option{-fassert}
@cindex @option{-fno-assert}
Turn off code generation for @code{assert} contracts.
@item -fno-bounds-check
@cindex @option{-fbounds-check}
@cindex @option{-fno-bounds-check}
Turns off array bounds checking for all functions, which can improve
performance for code that uses arrays extensively. Note that this
can result in unpredictable behavior if the code in question actually
does violate array bounds constraints. It is safe to use this option
if you are sure that your code never throws a @code{RangeError}.
@item -fbounds-check=@var{value}
@cindex @option{-fbounds-check=}
An alternative to @option{-fbounds-check} that allows more control
as to where bounds checking is turned on or off. The following values
are supported:
@table @samp
@item on
Turns on array bounds checking for all functions.
@item safeonly
Turns on array bounds checking only for @code{@@safe} functions.
@item off
Turns off array bounds checking completely.
@end table
@item -fno-builtin
@cindex @option{-fbuiltin}
@cindex @option{-fno-builtin}
Don't recognize built-in functions unless they begin with the prefix
@samp{__builtin_}. By default, the compiler will recognize when a
function in the @code{core.stdc} package is a built-in function.
@item -fcheckaction=@var{value}
@cindex @option{-fcheckaction}
This option controls what code is generated on an assertion, bounds check, or
final switch failure. The following values are supported:
@table @samp
@item context
Throw an @code{AssertError} with extra context information.
@item halt
Halt the program execution.
@item throw
Throw an @code{AssertError} (the default).
@end table
@item -fdebug
@item -fdebug=@var{value}
@cindex @option{-fdebug}
@cindex @option{-fno-debug}
Turn on compilation of conditional @code{debug} code into the program.
The @option{-fdebug} option itself sets the debug level to @code{1},
while @option{-fdebug=} enables @code{debug} code that are identified
by any of the following values:
@table @samp
@item level
Sets the debug level to @var{level}, any @code{debug} code <= @var{level}
is compiled into the program.
@item ident
Turns on compilation of any @code{debug} code identified by @var{ident}.
@end table
@item -fno-druntime
@cindex @option{-fdruntime}
@cindex @option{-fno-druntime}
Implements @uref{https://dlang.org/spec/betterc.html}. Assumes that
compilation targets an environment without a D runtime library.
This is equivalent to compiling with the following options:
@example
gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
@end example
@item -fextern-std=@var{standard}
@cindex @option{-fextern-std}
Sets the C++ name mangling compatibility to the version identified by
@var{standard}. The following values are supported:
@table @samp
@item c++98
@item c++03
Sets @code{__traits(getTargetInfo, "cppStd")} to @code{199711}.
@item c++11
Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201103}.
@item c++14
Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201402}.
@item c++17
Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201703}.
This is the default.
@item c++20
Sets @code{__traits(getTargetInfo, "cppStd")} to @code{202002}.
@end table
@item -fno-invariants
@cindex @option{-finvariants}
@cindex @option{-fno-invariants}
Turns off code generation for class @code{invariant} contracts.
@item -fmain
@cindex @option{-fmain}
Generates a default @code{main()} function when compiling. This is useful when
unittesting a library, as it enables running the unittests in a library without
having to manually define an entry-point function. This option does nothing
when @code{main} is already defined in user code.
@item -fno-moduleinfo
@cindex @option{-fmoduleinfo}
@cindex @option{-fno-moduleinfo}
Turns off generation of the @code{ModuleInfo} and related functions
that would become unreferenced without it, which may allow linking
to programs not written in D. Functions that are not be generated
include module constructors and destructors (@code{static this} and
@code{static ~this}), @code{unittest} code, and @code{DSO} registry
functions for dynamically linked code.
@item -fonly=@var{filename}
@cindex @option{-fonly}
Tells the compiler to parse and run semantic analysis on all modules
on the command line, but only generate code for the module specified
by @var{filename}.
@item -fno-postconditions
@cindex @option{-fpostconditions}
@cindex @option{-fno-postconditions}
Turns off code generation for postcondition @code{out} contracts.
@item -fno-preconditions
@cindex @option{-fpreconditions}
@cindex @option{-fno-preconditions}
Turns off code generation for precondition @code{in} contracts.
@item -fpreview=@var{id}
@cindex @option{-fpreview}
Turns on an upcoming D language change identified by @var{id}. The following
values are supported:
@table @samp
@item all
Turns on all upcoming D language features.
@item dip1000
Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md}
(Scoped pointers).
@item dip1008
Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md}
(Allow exceptions in @code{@@nogc} code).
@item dip1021
Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md}
(Mutable function arguments).
@item dip25
Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md}
(Sealed references).
@item dtorfields
Turns on generation for destructing fields of partially constructed objects.
@item fieldwise
Turns on generation of struct equality to use field-wise comparisons.
@item fixaliasthis
Implements new lookup rules that check the current scope for @code{alias this}
before searching in upper scopes.
@item fiximmutableconv
Disallows unsound immutable conversions that were formerly incorrectly
permitted.
@item in
Implements @code{in} parameters to mean @code{scope const [ref]} and accepts
rvalues.
@item inclusiveincontracts
Implements @code{in} contracts of overridden methods to be a superset of parent
contract.
@item intpromote
Implements C-style integral promotion for unary @code{+}, @code{-} and @code{~}
expressions.
@item nosharedaccess
Turns off and disallows all access to shared memory objects.
@item rvaluerefparam
Implements rvalue arguments to @code{ref} parameters.
@item systemvariables
Disables access to variables marked @code{@@system} from @code{@@safe} code.
@end table
@item -frelease
@cindex @option{-frelease}
@cindex @option{-fno-release}
Turns on compiling in release mode, which means not emitting runtime
checks for contracts and asserts. Array bounds checking is not done
for @code{@@system} and @code{@@trusted} functions, and assertion
failures are undefined behavior.
This is equivalent to compiling with the following options:
@example
gdc -fno-assert -fbounds-check=safe -fno-invariants \
-fno-postconditions -fno-preconditions -fno-switch-errors
@end example
@item -frevert=
@cindex @option{-frevert}
Turns off a D language feature identified by @var{id}. The following values
are supported:
@table @samp
@item all
Turns off all revertable D language features.
@item dip25
Reverts @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md}
(Sealed references).
@item dtorfields
Turns off generation for destructing fields of partially constructed objects.
@item markdown
Turns off Markdown replacements in Ddoc comments.
@end table
@item -fno-rtti
@cindex @option{-frtti}
@cindex @option{-fno-rtti}
Turns off generation of run-time type information for all user defined types.
Any code that uses features of the language that require access to this
information will result in an error.
@item -fno-switch-errors
@cindex @option{-fswitch-errors}
@cindex @option{-fno-switch-errors}
This option controls what code is generated when no case is matched
in a @code{final switch} statement. The default run time behavior
is to throw a @code{SwitchError}. Turning off @option{-fswitch-errors}
means that instead the execution of the program is immediately halted.
@item -funittest
@cindex @option{-funittest}
@cindex @option{-fno-unittest}
Turns on compilation of @code{unittest} code, and turns on the
@code{version(unittest)} identifier. This implies @option{-fassert}.
@item -fversion=@var{value}
@cindex @option{-fversion}
Turns on compilation of conditional @code{version} code into the program
identified by any of the following values:
@table @samp
@item level
Sets the version level to @var{level}, any @code{version} code >= @var{level}
is compiled into the program.
@item ident
Turns on compilation of @code{version} code identified by @var{ident}.
@end table
@item -fno-weak-templates
@cindex @option{-fweak-templates}
@cindex @option{-fno-weak-templates}
Turns off emission of declarations that can be defined in multiple objects as
weak symbols. The default is to emit all public symbols as weak, unless the
target lacks support for weak symbols. Disabling this option means that common
symbols are instead put in COMDAT or become private.
@end table
@node Directory Options
@section Options for Directory Search
@cindex directory options
@cindex options, directory search
@cindex search path
These options specify directories to search for files, libraries, and
other parts of the compiler:
@table @gcctabopt
@item -I@var{dir}
@cindex @option{-I}
Specify a directory to use when searching for imported modules at
compile time. Multiple @option{-I} options can be used, and the
paths are searched in the same order.
@item -J@var{dir}
@cindex @option{-J}
Specify a directory to use when searching for files in string imports
at compile time. This switch is required in order to use
@code{import(file)} expressions. Multiple @option{-J} options can be
used, and the paths are searched in the same order.
@item -L@var{dir}
@cindex @option{-L}
When linking, specify a library search directory, as with @command{gcc}.
@item -B@var{dir}
@cindex @option{-B}
This option specifies where to find the executables, libraries,
source files, and data files of the compiler itself, as with @command{gcc}.
@item -fmodule-file=@var{module}=@var{spec}
@cindex @option{-fmodule-file}
This option manipulates file paths of imported modules, such that if an
imported module matches all or the leftmost part of @var{module}, the file
path in @var{spec} is used as the location to search for D sources.
This is used when the source file path and names are not the same as the
package and module hierarchy. Consider the following examples:
@example
gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar
@end example
This will tell the compiler to search in all import paths for the source
file @var{foo.d} when importing @var{A.B}, and the directory @var{bar/}
when importing @var{C}, as annotated in the following D code:
@example
module test;
import A.B; // Matches A.B, searches for foo.d
import C.D.E; // Matches C, searches for bar/D/E.d
import A.B.C; // No match, searches for A/B/C.d
@end example
@item -imultilib @var{dir}
@cindex @option{-imultilib}
Use @var{dir} as a subdirectory of the gcc directory containing
target-specific D sources and interfaces.
@item -iprefix @var{prefix}
@cindex @option{-iprefix}
Specify @var{prefix} as the prefix for the gcc directory containing
target-specific D sources and interfaces. If the @var{prefix} represents
a directory, you should include the final @code{'/'}.
@item -nostdinc
@cindex @option{-nostdinc}
Do not search the standard system directories for D source and interface
files. Only the directories that have been specified with @option{-I} options
(and the directory of the current file, if appropriate) are searched.
@end table
@node Code Generation
@section Code Generation
@cindex options, code generation
In addition to the many @command{gcc} options controlling code generation,
@command{gdc} has several options specific to itself.
@table @gcctabopt
@item -H
@cindex @option{-H}
Generates D interface files for all modules being compiled. The compiler
determines the output file based on the name of the input file, removes
any directory components and suffix, and applies the @file{.di} suffix.
@item -Hd @var{dir}
@cindex @option{-Hd}
Same as @option{-H}, but writes interface files to directory @var{dir}.
This option can be used with @option{-Hf @var{file}} to independently set the
output file and directory path.
@item -Hf @var{file}
@cindex @option{-Hf}
Same as @option{-H} but writes interface files to @var{file}. This option can
be used with @option{-Hd @var{dir}} to independently set the output file and
directory path.
@item -M
@cindex @option{-M}
Output the module dependencies of all source files being compiled in a
format suitable for @command{make}. The compiler outputs one
@command{make} rule containing the object file name for that source file,
a colon, and the names of all imported files.
@item -MM
@cindex @option{-MM}
Like @option{-M} but does not mention imported modules from the D standard
library package directories.
@item -MF @var{file}
@cindex @option{-MF}
When used with @option{-M} or @option{-MM}, specifies a @var{file} to write
the dependencies to. When used with the driver options @option{-MD} or
@option{-MMD}, @option{-MF} overrides the default dependency output file.
@item -MG
@cindex @option{-MG}
This option is for compatibility with @command{gcc}, and is ignored by the
compiler.
@item -MP
@cindex @option{-MP}
Outputs a phony target for each dependency other than the modules being
compiled, causing each to depend on nothing.
@item -MT @var{target}
@cindex @option{-MT}
Change the @var{target} of the rule emitted by dependency generation
to be exactly the string you specify. If you want multiple targets,
you can specify them as a single argument to @option{-MT}, or use
multiple @option{-MT} options.
@item -MQ @var{target}
@cindex @option{-MQ}
Same as @option{-MT}, but it quotes any characters which are special to
@command{make}.
@item -MD
@cindex @option{-MD}
This option is equivalent to @option{-M -MF @var{file}}. The driver
determines @var{file} by removing any directory components and suffix
from the input file, and then adding a @file{.deps} suffix.
@item -MMD
@cindex @option{-MMD}
Like @option{-MD} but does not mention imported modules from the D standard
library package directories.
@item -X
@cindex @option{-X}
Output information describing the contents of all source files being
compiled in JSON format to a file. The driver determines @var{file} by
removing any directory components and suffix from the input file, and then
adding a @file{.json} suffix.
@item -Xf @var{file}
@cindex @option{-Xf}
Same as @option{-X}, but writes all JSON contents to the specified
@var{file}.
@item -fdoc
@cindex @option{-fdoc}
Generates @code{Ddoc} documentation and writes it to a file. The compiler
determines @var{file} by removing any directory components and suffix
from the input file, and then adding a @file{.html} suffix.
@item -fdoc-dir=@var{dir}
@cindex @option{-fdoc-dir}
Same as @option{-fdoc}, but writes documentation to directory @var{dir}.
This option can be used with @option{-fdoc-file=@var{file}} to
independently set the output file and directory path.
@item -fdoc-file=@var{file}
@cindex @option{-fdoc-file}
Same as @option{-fdoc}, but writes documentation to @var{file}. This
option can be used with @option{-fdoc-dir=@var{dir}} to independently
set the output file and directory path.
@item -fdoc-inc=@var{file}
@cindex @option{-fdoc-inc}
Specify @var{file} as a @var{Ddoc} macro file to be read. Multiple
@option{-fdoc-inc} options can be used, and files are read and processed
in the same order.
@item -fdump-c++-spec=@var{file}
For D source files, generate corresponding C++ declarations in @var{file}.
@item -fdump-c++-spec-verbose
In conjunction with @option{-fdump-c++-spec=} above, add comments for ignored
declarations in the generated C++ header.
@item -fsave-mixins=@var{file}
@cindex @option{-fsave-mixins}
Generates code expanded from D @code{mixin} statements and writes the
processed sources to @var{file}. This is useful to debug errors in compilation
and provides source for debuggers to show when requested.
@end table
@node Warnings
@section Warnings
@cindex options to control warnings
@cindex warning messages
@cindex messages, warning
@cindex suppressing warnings
Warnings are diagnostic messages that report constructions that
are not inherently erroneous but that are risky or suggest there
is likely to be a bug in the program. Unless @option{-Werror} is
specified, they do not prevent compilation of the program.
@table @gcctabopt
@item -Wall
@cindex @option{-Wall}
@cindex @option{-Wno-all}
Turns on all warnings messages. Warnings are not a defined part of
the D language, and all constructs for which this may generate a
warning message are valid code.
@item -Walloca
@cindex @option{-Walloca}
This option warns on all uses of "alloca" in the source.
@item -Walloca-larger-than=@var{n}
@cindex @option{-Walloca-larger-than}
@cindex @option{-Wno-alloca-larger-than}
Warn on unbounded uses of alloca, and on bounded uses of alloca
whose bound can be larger than @var{n} bytes.
@option{-Wno-alloca-larger-than} disables
@option{-Walloca-larger-than} warning and is equivalent to
@option{-Walloca-larger-than=@var{SIZE_MAX}} or larger.
@item -Wcast-result
@cindex @option{-Wcast-result}
@cindex @option{-Wno-cast-result}
Warn about casts that will produce a null or zero result. Currently
this is only done for casting between an imaginary and non-imaginary
data type, or casting between a D and C++ class.
@item -Wno-deprecated
@cindex @option{-Wdeprecated}
@cindex @option{-Wno-deprecated}
Do not warn about usage of deprecated features and symbols with
@code{deprecated} attributes.
@item -Werror
@cindex @option{-Werror}
@cindex @option{-Wno-error}
Turns all warnings into errors.
@item -Wspeculative
@cindex @option{-Wspeculative}
@cindex @option{-Wno-speculative}
List all error messages from speculative compiles, such as
@code{__traits(compiles, ...)}. This option does not report
messages as warnings, and these messages therefore never become
errors when the @option{-Werror} option is also used.
@item -Wtemplates
@cindex @option{-Wtemplates}
@cindex @option{-Wno-templates}
Warn when a template instantiation is encountered. Some coding
rules disallow templates, and this may be used to enforce that rule.
@item -Wunknown-pragmas
@cindex @option{-Wunknown-pragmas}
@cindex @option{-Wno-unknown-pragmas}
Warn when a @code{pragma()} is encountered that is not understood by
@command{gdc}. This differs from @option{-fignore-unknown-pragmas}
where a pragma that is part of the D language, but not implemented by
the compiler, won't get reported.
@item -Wno-varargs
@cindex Wvarargs
@cindex Wno-varargs
Do not warn upon questionable usage of the macros used to handle variable
arguments like @code{va_start}.
@item -fignore-unknown-pragmas
@cindex @option{-fignore-unknown-pragmas}
@cindex @option{-fno-ignore-unknown-pragmas}
Turns off errors for unsupported pragmas.
@item -fmax-errors=@var{n}
@cindex @option{-fmax-errors}
Limits the maximum number of error messages to @var{n}, at which point
@command{gdc} bails out rather than attempting to continue processing the
source code. If @var{n} is 0 (the default), there is no limit on the
number of error messages produced.
@item -fsyntax-only
@cindex @option{-fsyntax-only}
@cindex @option{-fno-syntax-only}
Check the code for syntax errors, but do not actually compile it. This
can be used in conjunction with @option{-fdoc} or @option{-H} to generate
files for each module present on the command-line, but no other output
file.
@item -ftransition=@var{id}
@cindex @option{-ftransition}
Report additional information about D language changes identified by
@var{id}. The following values are supported:
@table @samp
@item all
List information on all D language transitions.
@item complex
List all usages of complex or imaginary types.
@item field
List all non-mutable fields which occupy an object instance.
@item in
List all usages of @code{in} on parameter.
@item nogc
List all hidden GC allocations.
@item templates
List statistics on template instantiations.
@item tls
List all variables going into thread local storage.
@item vmarkdown
List instances of Markdown replacements in Ddoc.
@end table
@end table
@node Linking
@section Options for Linking
@cindex options, linking
@cindex linking, static
These options come into play when the compiler links object files into an
executable output file. They are meaningless if the compiler is not doing
a link step.
@table @gcctabopt
@item -defaultlib=@var{libname}
@cindex @option{-defaultlib=}
Specify the library to use instead of libphobos when linking. Options
specifying the linkage of libphobos, such as @option{-static-libphobos}
or @option{-shared-libphobos}, are ignored.
@item -debuglib=@var{libname}
@cindex @option{-debuglib=}
Specify the debug library to use instead of libphobos when linking.
This option has no effect unless the @option{-g} option was also given
on the command line. Options specifying the linkage of libphobos, such
as @option{-static-libphobos} or @option{-shared-libphobos}, are ignored.
@item -nophoboslib
@cindex @option{-nophoboslib}
Do not use the Phobos or D runtime library when linking. Options specifying
the linkage of libphobos, such as @option{-static-libphobos} or
@option{-shared-libphobos}, are ignored. The standard system libraries are
used normally, unless @option{-nostdlib} or @option{-nodefaultlibs} is used.
@item -shared-libphobos
@cindex @option{-shared-libphobos}
On systems that provide @file{libgphobos} and @file{libgdruntime} as a
shared and a static library, this option forces the use of the shared
version. If no shared version was built when the compiler was configured,
this option has no effect.
@item -static-libphobos
@cindex @option{-static-libphobos}
On systems that provide @file{libgphobos} and @file{libgdruntime} as a
shared and a static library, this option forces the use of the static
version. If no static version was built when the compiler was configured,
this option has no effect.
@end table
@node Developer Options
@section Developer Options
@cindex developer options
@cindex debug dump options
@cindex dump options
This section describes command-line options that are primarily of
interest to developers or language tooling.
@table @gcctabopt
@item -fdump-d-original
@cindex @option{-fdump-d-original}
Output the internal front-end AST after the @code{semantic3} stage.
This option is only useful for debugging the GNU D compiler itself.
@item -v
@cindex @option{-v}
Dump information about the compiler language processing stages as the source
program is being compiled. This includes listing all modules that are
processed through the @code{parse}, @code{semantic}, @code{semantic2}, and
@code{semantic3} stages; all @code{import} modules and their file paths;
and all @code{function} bodies that are being compiled.
@end table
@c man end
@node Index
@unnumbered Index
@printindex cp
@bye

569
gcc/doc/analyzer.texi Normal file
View File

@ -0,0 +1,569 @@
@c Copyright (C) 2019-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@c Contributed by David Malcolm <dmalcolm@redhat.com>.
@node Static Analyzer
@chapter Static Analyzer
@cindex analyzer
@cindex static analysis
@cindex static analyzer
@menu
* Analyzer Internals:: Analyzer Internals
* Debugging the Analyzer:: Useful debugging tips
@end menu
@node Analyzer Internals
@section Analyzer Internals
@cindex analyzer, internals
@cindex static analyzer, internals
@subsection Overview
The analyzer implementation works on the gimple-SSA representation.
(I chose this in the hopes of making it easy to work with LTO to
do whole-program analysis).
The implementation is read-only: it doesn't attempt to change anything,
just emit warnings.
The gimple representation can be seen using @option{-fdump-ipa-analyzer}.
@quotation Tip
If the analyzer ICEs before this is written out, one workaround is to use
@option{--param=analyzer-bb-explosion-factor=0} to force the analyzer
to bail out after analyzing the first basic block.
@end quotation
First, we build a @code{supergraph} which combines the callgraph and all
of the CFGs into a single directed graph, with both interprocedural and
intraprocedural edges. The nodes and edges in the supergraph are called
``supernodes'' and ``superedges'', and often referred to in code as
@code{snodes} and @code{sedges}. Basic blocks in the CFGs are split at
interprocedural calls, so there can be more than one supernode per
basic block. Most statements will be in just one supernode, but a call
statement can appear in two supernodes: at the end of one for the call,
and again at the start of another for the return.
The supergraph can be seen using @option{-fdump-analyzer-supergraph}.
We then build an @code{analysis_plan} which walks the callgraph to
determine which calls might be suitable for being summarized (rather
than fully explored) and thus in what order to explore the functions.
Next is the heart of the analyzer: we use a worklist to explore state
within the supergraph, building an "exploded graph".
Nodes in the exploded graph correspond to <point,@w{ }state> pairs, as in
"Precise Interprocedural Dataflow Analysis via Graph Reachability"
(Thomas Reps, Susan Horwitz and Mooly Sagiv).
We reuse nodes for <point, state> pairs we've already seen, and avoid
tracking state too closely, so that (hopefully) we rapidly converge
on a final exploded graph, and terminate the analysis. We also bail
out if the number of exploded <end-of-basic-block, state> nodes gets
larger than a particular multiple of the total number of basic blocks
(to ensure termination in the face of pathological state-explosion
cases, or bugs). We also stop exploring a point once we hit a limit
of states for that point.
We can identify problems directly when processing a <point,@w{ }state>
instance. For example, if we're finding the successors of
@smallexample
<point: before-stmt: "free (ptr);",
state: @{"ptr": freed@}>
@end smallexample
then we can detect a double-free of "ptr". We can then emit a path
to reach the problem by finding the simplest route through the graph.
Program points in the analysis are much more fine-grained than in the
CFG and supergraph, with points (and thus potentially exploded nodes)
for various events, including before individual statements.
By default the exploded graph merges multiple consecutive statements
in a supernode into one exploded edge to minimize the size of the
exploded graph. This can be suppressed via
@option{-fanalyzer-fine-grained}.
The fine-grained approach seems to make things simpler and more debuggable
that other approaches I tried, in that each point is responsible for one
thing.
Program points in the analysis also have a "call string" identifying the
stack of callsites below them, so that paths in the exploded graph
correspond to interprocedurally valid paths: we always return to the
correct call site, propagating state information accordingly.
We avoid infinite recursion by stopping the analysis if a callsite
appears more than @code{analyzer-max-recursion-depth} in a callstring
(defaulting to 2).
@subsection Graphs
Nodes and edges in the exploded graph are called ``exploded nodes'' and
``exploded edges'' and often referred to in the code as
@code{enodes} and @code{eedges} (especially when distinguishing them
from the @code{snodes} and @code{sedges} in the supergraph).
Each graph numbers its nodes, giving unique identifiers - supernodes
are referred to throughout dumps in the form @samp{SN': @var{index}} and
exploded nodes in the form @samp{EN: @var{index}} (e.g. @samp{SN: 2} and
@samp{EN:29}).
The supergraph can be seen using @option{-fdump-analyzer-supergraph-graph}.
The exploded graph can be seen using @option{-fdump-analyzer-exploded-graph}
and other dump options. Exploded nodes are color-coded in the .dot output
based on state-machine states to make it easier to see state changes at
a glance.
@subsection State Tracking
There's a tension between:
@itemize @bullet
@item
precision of analysis in the straight-line case, vs
@item
exponential blow-up in the face of control flow.
@end itemize
For example, in general, given this CFG:
@smallexample
A
/ \
B C
\ /
D
/ \
E F
\ /
G
@end smallexample
we want to avoid differences in state-tracking in B and C from
leading to blow-up. If we don't prevent state blowup, we end up
with exponential growth of the exploded graph like this:
@smallexample
1:A
/ \
/ \
/ \
2:B 3:C
| |
4:D 5:D (2 exploded nodes for D)
/ \ / \
6:E 7:F 8:E 9:F
| | | |
10:G 11:G 12:G 13:G (4 exploded nodes for G)
@end smallexample
Similar issues arise with loops.
To prevent this, we follow various approaches:
@enumerate a
@item
state pruning: which tries to discard state that won't be relevant
later on withing the function.
This can be disabled via @option{-fno-analyzer-state-purge}.
@item
state merging. We can try to find the commonality between two
program_state instances to make a third, simpler program_state.
We have two strategies here:
@enumerate
@item
the worklist keeps new nodes for the same program_point together,
and tries to merge them before processing, and thus before they have
successors. Hence, in the above, the two nodes for D (4 and 5) reach
the front of the worklist together, and we create a node for D with
the merger of the incoming states.
@item
try merging with the state of existing enodes for the program_point
(which may have already been explored). There will be duplication,
but only one set of duplication; subsequent duplicates are more likely
to hit the cache. In particular, (hopefully) all merger chains are
finite, and so we guarantee termination.
This is intended to help with loops: we ought to explore the first
iteration, and then have a "subsequent iterations" exploration,
which uses a state merged from that of the first, to be more abstract.
@end enumerate
We avoid merging pairs of states that have state-machine differences,
as these are the kinds of differences that are likely to be most
interesting. So, for example, given:
@smallexample
if (condition)
ptr = malloc (size);
else
ptr = local_buf;
.... do things with 'ptr'
if (condition)
free (ptr);
...etc
@end smallexample
then we end up with an exploded graph that looks like this:
@smallexample
if (condition)
/ T \ F
--------- ----------
/ \
ptr = malloc (size) ptr = local_buf
| |
copy of copy of
"do things with 'ptr'" "do things with 'ptr'"
with ptr: heap-allocated with ptr: stack-allocated
| |
if (condition) if (condition)
| known to be T | known to be F
free (ptr); |
\ /
-----------------------------
| ('ptr' is pruned, so states can be merged)
etc
@end smallexample
where some duplication has occurred, but only for the places where the
the different paths are worth exploringly separately.
Merging can be disabled via @option{-fno-analyzer-state-merge}.
@end enumerate
@subsection Region Model
Part of the state stored at a @code{exploded_node} is a @code{region_model}.
This is an implementation of the region-based ternary model described in
@url{https://www.researchgate.net/publication/221430855_A_Memory_Model_for_Static_Analysis_of_C_Programs,
"A Memory Model for Static Analysis of C Programs"}
(Zhongxing Xu, Ted Kremenek, and Jian Zhang).
A @code{region_model} encapsulates a representation of the state of
memory, with a @code{store} recording a binding between @code{region}
instances, to @code{svalue} instances. The bindings are organized into
clusters, where regions accessible via well-defined pointer arithmetic
are in the same cluster. The representation is graph-like because values
can be pointers to regions. It also stores a constraint_manager,
capturing relationships between the values.
Because each node in the @code{exploded_graph} has a @code{region_model},
and each of the latter is graph-like, the @code{exploded_graph} is in some
ways a graph of graphs.
Here's an example of printing a @code{program_state}, showing the
@code{region_model} within it, along with state for the @code{malloc}
state machine.
@smallexample
(gdb) call debug (*this)
rmodel:
stack depth: 1
frame (index 0): frame: ‘test’@@1
clusters within frame: ‘test’@@1
cluster for: ptr_3: &HEAP_ALLOCATED_REGION(12)
m_called_unknown_fn: FALSE
constraint_manager:
equiv classes:
constraints:
malloc:
0x2e89590: &HEAP_ALLOCATED_REGION(12): unchecked ('ptr_3')
@end smallexample
This is the state at the point of returning from @code{calls_malloc} back
to @code{test} in the following:
@smallexample
void *
calls_malloc (void)
@{
void *result = malloc (1024);
return result;
@}
void test (void)
@{
void *ptr = calls_malloc ();
/* etc. */
@}
@end smallexample
Within the store, there is the cluster for @code{ptr_3} within the frame
for @code{test}, where the whole cluster is bound to a pointer value,
pointing at @code{HEAP_ALLOCATED_REGION(12)}. Additionally, this pointer
has the @code{unchecked} state for the @code{malloc} state machine
indicating it hasn't yet been checked against NULL since the allocation
call.
@subsection Analyzer Paths
We need to explain to the user what the problem is, and to persuade them
that there really is a problem. Hence having a @code{diagnostic_path}
isn't just an incidental detail of the analyzer; it's required.
Paths ought to be:
@itemize @bullet
@item
interprocedurally-valid
@item
feasible
@end itemize
Without state-merging, all paths in the exploded graph are feasible
(in terms of constraints being satisfied).
With state-merging, paths in the exploded graph can be infeasible.
We collate warnings and only emit them for the simplest path
e.g. for a bug in a utility function, with lots of routes to calling it,
we only emit the simplest path (which could be intraprocedural, if
it can be reproduced without a caller).
We thus want to find the shortest feasible path through the exploded
graph from the origin to the exploded node at which the diagnostic was
saved. Unfortunately, if we simply find the shortest such path and
check if it's feasible we might falsely reject the diagnostic, as there
might be a longer path that is feasible. Examples include the cases
where the diagnostic requires us to go at least once around a loop for a
later condition to be satisfied, or where for a later condition to be
satisfied we need to enter a suite of code that the simpler path skips.
We attempt to find the shortest feasible path to each diagnostic by
first constructing a ``trimmed graph'' from the exploded graph,
containing only those nodes and edges from which there are paths to
the target node, and using Dijkstra's algorithm to order the trimmed
nodes by minimal distance to the target.
We then use a worklist to iteratively build a ``feasible graph''
(actually a tree), capturing the pertinent state along each path, in
which every path to a ``feasible node'' is feasible by construction,
restricting ourselves to the trimmed graph to ensure we stay on target,
and ordering the worklist so that the first feasible path we find to the
target node is the shortest possible path. Hence we start by trying the
shortest possible path, but if that fails, we explore progressively
longer paths, eventually trying iterations through loops. The
exploration is captured in the feasible_graph, which can be dumped as a
.dot file via @option{-fdump-analyzer-feasibility} to visualize the
exploration. The indices of the feasible nodes show the order in which
they were created. We effectively explore the tree of feasible paths in
order of shortest path until we either find a feasible path to the
target node, or hit a limit and give up.
This is something of a brute-force approach, but the trimmed graph
hopefully keeps the complexity manageable.
This algorithm can be disabled (for debugging purposes) via
@option{-fno-analyzer-feasibility}, which simply uses the shortest path,
and notes if it is infeasible.
The above gives us a shortest feasible @code{exploded_path} through the
@code{exploded_graph} (a list of @code{exploded_edge *}). We use this
@code{exploded_path} to build a @code{diagnostic_path} (a list of
@strong{events} for the diagnostic subsystem) - specifically a
@code{checker_path}.
Having built the @code{checker_path}, we prune it to try to eliminate
events that aren't relevant, to minimize how much the user has to read.
After pruning, we notify each event in the path of its ID and record the
IDs of interesting events, allowing for events to refer to other events
in their descriptions. The @code{pending_diagnostic} class has various
vfuncs to support emitting more precise descriptions, so that e.g.
@itemize @bullet
@item
a deref-of-unchecked-malloc diagnostic might use:
@smallexample
returning possibly-NULL pointer to 'make_obj' from 'allocator'
@end smallexample
for a @code{return_event} to make it clearer how the unchecked value moves
from callee back to caller
@item
a double-free diagnostic might use:
@smallexample
second 'free' here; first 'free' was at (3)
@end smallexample
and a use-after-free might use
@smallexample
use after 'free' here; memory was freed at (2)
@end smallexample
@end itemize
At this point we can emit the diagnostic.
@subsection Limitations
@itemize @bullet
@item
Only for C so far
@item
The implementation of call summaries is currently very simplistic.
@item
Lack of function pointer analysis
@item
The constraint-handling code assumes reflexivity in some places
(that values are equal to themselves), which is not the case for NaN.
As a simple workaround, constraints on floating-point values are
currently ignored.
@item
There are various other limitations in the region model (grep for TODO/xfail
in the testsuite).
@item
The constraint_manager's implementation of transitivity is currently too
expensive to enable by default and so must be manually enabled via
@option{-fanalyzer-transitivity}).
@item
The checkers are currently hardcoded and don't allow for user extensibility
(e.g. adding allocate/release pairs).
@item
Although the analyzer's test suite has a proof-of-concept test case for
LTO, LTO support hasn't had extensive testing. There are various
lang-specific things in the analyzer that assume C rather than LTO.
For example, SSA names are printed to the user in ``raw'' form, rather
than printing the underlying variable name.
@end itemize
Some ideas for other checkers
@itemize @bullet
@item
File-descriptor-based APIs
@item
Linux kernel internal APIs
@item
Signal handling
@end itemize
@node Debugging the Analyzer
@section Debugging the Analyzer
@cindex analyzer, debugging
@cindex static analyzer, debugging
@subsection Special Functions for Debugging the Analyzer
The analyzer recognizes various special functions by name, for use
in debugging the analyzer. Declarations can be seen in the testsuite
in @file{analyzer-decls.h}. None of these functions are actually
implemented.
Add:
@smallexample
__analyzer_break ();
@end smallexample
to the source being analyzed to trigger a breakpoint in the analyzer when
that source is reached. By putting a series of these in the source, it's
much easier to effectively step through the program state as it's analyzed.
The analyzer handles:
@smallexample
__analyzer_describe (0, expr);
@end smallexample
by emitting a warning describing the 2nd argument (which can be of any
type), at a verbosity level given by the 1st argument. This is for use when
debugging, and may be of use in DejaGnu tests.
@smallexample
__analyzer_dump ();
@end smallexample
will dump the copious information about the analyzer's state each time it
reaches the call in its traversal of the source.
@smallexample
extern void __analyzer_dump_capacity (const void *ptr);
@end smallexample
will emit a warning describing the capacity of the base region of
the region pointed to by the 1st argument.
@smallexample
extern void __analyzer_dump_escaped (void);
@end smallexample
will emit a warning giving the number of decls that have escaped on this
analysis path, followed by a comma-separated list of their names,
in alphabetical order.
@smallexample
__analyzer_dump_path ();
@end smallexample
will emit a placeholder ``note'' diagnostic with a path to that call site,
if the analyzer finds a feasible path to it.
The builtin @code{__analyzer_dump_exploded_nodes} will emit a warning
after analysis containing information on all of the exploded nodes at that
program point:
@smallexample
__analyzer_dump_exploded_nodes (0);
@end smallexample
will output the number of ``processed'' nodes, and the IDs of
both ``processed'' and ``merger'' nodes, such as:
@smallexample
warning: 2 processed enodes: [EN: 56, EN: 58] merger(s): [EN: 54-55, EN: 57, EN: 59]
@end smallexample
With a non-zero argument
@smallexample
__analyzer_dump_exploded_nodes (1);
@end smallexample
it will also dump all of the states within the ``processed'' nodes.
@smallexample
__analyzer_dump_region_model ();
@end smallexample
will dump the region_model's state to stderr.
@smallexample
__analyzer_dump_state ("malloc", ptr);
@end smallexample
will emit a warning describing the state of the 2nd argument
(which can be of any type) with respect to the state machine with
a name matching the 1st argument (which must be a string literal).
This is for use when debugging, and may be of use in DejaGnu tests.
@smallexample
__analyzer_eval (expr);
@end smallexample
will emit a warning with text "TRUE", FALSE" or "UNKNOWN" based on the
truthfulness of the argument. This is useful for writing DejaGnu tests.
@smallexample
__analyzer_get_unknown_ptr ();
@end smallexample
will obtain an unknown @code{void *}.
@subsection Other Debugging Techniques
The option @option{-fdump-analyzer-json} will dump both the supergraph
and the exploded graph in compressed JSON form.
One approach when tracking down where a particular bogus state is
introduced into the @code{exploded_graph} is to add custom code to
@code{program_state::validate}.
The debug function @code{region::is_named_decl_p} can be used when debugging,
such as for assertions and conditional breakpoints. For example, when
tracking down a bug in handling a decl called @code{yy_buffer_stack}, I
temporarily added a:
@smallexample
gcc_assert (!m_base_region->is_named_decl_p ("yy_buffer_stack"));
@end smallexample
to @code{binding_cluster::mark_as_escaped} to trap a point where
@code{yy_buffer_stack} was mistakenly being treated as having escaped.

83
gcc/doc/avr-mmcu.texi Normal file
View File

@ -0,0 +1,83 @@
@c Copyright (C) 2012-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc/doc/include/fdl.texi.
@c This file is generated automatically using
@c gcc/config/avr/gen-avr-mmcu-texi.cc from:
@c gcc/config/avr/avr-arch.h
@c gcc/config/avr/avr-devices.cc
@c gcc/config/avr/avr-mcus.def
@c Please do not edit manually.
@table @code
@item avr2
``Classic'' devices with up to 8@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{attiny22}, @code{attiny26}, @code{at90s2313}, @code{at90s2323}, @code{at90s2333}, @code{at90s2343}, @code{at90s4414}, @code{at90s4433}, @code{at90s4434}, @code{at90c8534}, @code{at90s8515}, @code{at90s8535}.
@item avr25
``Classic'' devices with up to 8@tie{}KiB of program memory and with the @code{MOVW} instruction.
@*@var{mcu}@tie{}= @code{attiny13}, @code{attiny13a}, @code{attiny24}, @code{attiny24a}, @code{attiny25}, @code{attiny261}, @code{attiny261a}, @code{attiny2313}, @code{attiny2313a}, @code{attiny43u}, @code{attiny44}, @code{attiny44a}, @code{attiny45}, @code{attiny48}, @code{attiny441}, @code{attiny461}, @code{attiny461a}, @code{attiny4313}, @code{attiny84}, @code{attiny84a}, @code{attiny85}, @code{attiny87}, @code{attiny88}, @code{attiny828}, @code{attiny841}, @code{attiny861}, @code{attiny861a}, @code{ata5272}, @code{ata6616c}, @code{at86rf401}.
@item avr3
``Classic'' devices with 16@tie{}KiB up to 64@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{at76c711}, @code{at43usb355}.
@item avr31
``Classic'' devices with 128@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{atmega103}, @code{at43usb320}.
@item avr35
``Classic'' devices with 16@tie{}KiB up to 64@tie{}KiB of program memory and with the @code{MOVW} instruction.
@*@var{mcu}@tie{}= @code{attiny167}, @code{attiny1634}, @code{atmega8u2}, @code{atmega16u2}, @code{atmega32u2}, @code{ata5505}, @code{ata6617c}, @code{ata664251}, @code{at90usb82}, @code{at90usb162}.
@item avr4
``Enhanced'' devices with up to 8@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{atmega48}, @code{atmega48a}, @code{atmega48p}, @code{atmega48pa}, @code{atmega48pb}, @code{atmega8}, @code{atmega8a}, @code{atmega8hva}, @code{atmega88}, @code{atmega88a}, @code{atmega88p}, @code{atmega88pa}, @code{atmega88pb}, @code{atmega8515}, @code{atmega8535}, @code{ata6285}, @code{ata6286}, @code{ata6289}, @code{ata6612c}, @code{at90pwm1}, @code{at90pwm2}, @code{at90pwm2b}, @code{at90pwm3}, @code{at90pwm3b}, @code{at90pwm81}.
@item avr5
``Enhanced'' devices with 16@tie{}KiB up to 64@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{atmega16}, @code{atmega16a}, @code{atmega16hva}, @code{atmega16hva2}, @code{atmega16hvb}, @code{atmega16hvbrevb}, @code{atmega16m1}, @code{atmega16u4}, @code{atmega161}, @code{atmega162}, @code{atmega163}, @code{atmega164a}, @code{atmega164p}, @code{atmega164pa}, @code{atmega165}, @code{atmega165a}, @code{atmega165p}, @code{atmega165pa}, @code{atmega168}, @code{atmega168a}, @code{atmega168p}, @code{atmega168pa}, @code{atmega168pb}, @code{atmega169}, @code{atmega169a}, @code{atmega169p}, @code{atmega169pa}, @code{atmega32}, @code{atmega32a}, @code{atmega32c1}, @code{atmega32hvb}, @code{atmega32hvbrevb}, @code{atmega32m1}, @code{atmega32u4}, @code{atmega32u6}, @code{atmega323}, @code{atmega324a}, @code{atmega324p}, @code{atmega324pa}, @code{atmega324pb}, @code{atmega325}, @code{atmega325a}, @code{atmega325p}, @code{atmega325pa}, @code{atmega328}, @code{atmega328p}, @code{atmega328pb}, @code{atmega329}, @code{atmega329a}, @code{atmega329p}, @code{atmega329pa}, @code{atmega3250}, @code{atmega3250a}, @code{atmega3250p}, @code{atmega3250pa}, @code{atmega3290}, @code{atmega3290a}, @code{atmega3290p}, @code{atmega3290pa}, @code{atmega406}, @code{atmega64}, @code{atmega64a}, @code{atmega64c1}, @code{atmega64hve}, @code{atmega64hve2}, @code{atmega64m1}, @code{atmega64rfr2}, @code{atmega640}, @code{atmega644}, @code{atmega644a}, @code{atmega644p}, @code{atmega644pa}, @code{atmega644rfr2}, @code{atmega645}, @code{atmega645a}, @code{atmega645p}, @code{atmega649}, @code{atmega649a}, @code{atmega649p}, @code{atmega6450}, @code{atmega6450a}, @code{atmega6450p}, @code{atmega6490}, @code{atmega6490a}, @code{atmega6490p}, @code{ata5795}, @code{ata5790}, @code{ata5790n}, @code{ata5791}, @code{ata6613c}, @code{ata6614q}, @code{ata5782}, @code{ata5831}, @code{ata8210}, @code{ata8510}, @code{ata5702m322}, @code{at90pwm161}, @code{at90pwm216}, @code{at90pwm316}, @code{at90can32}, @code{at90can64}, @code{at90scr100}, @code{at90usb646}, @code{at90usb647}, @code{at94k}, @code{m3000}.
@item avr51
``Enhanced'' devices with 128@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{atmega128}, @code{atmega128a}, @code{atmega128rfa1}, @code{atmega128rfr2}, @code{atmega1280}, @code{atmega1281}, @code{atmega1284}, @code{atmega1284p}, @code{atmega1284rfr2}, @code{at90can128}, @code{at90usb1286}, @code{at90usb1287}.
@item avr6
``Enhanced'' devices with 3-byte PC, i.e.@: with more than 128@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{atmega256rfr2}, @code{atmega2560}, @code{atmega2561}, @code{atmega2564rfr2}.
@item avrxmega2
``XMEGA'' devices with more than 8@tie{}KiB and up to 64@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{atxmega8e5}, @code{atxmega16a4}, @code{atxmega16a4u}, @code{atxmega16c4}, @code{atxmega16d4}, @code{atxmega16e5}, @code{atxmega32a4}, @code{atxmega32a4u}, @code{atxmega32c3}, @code{atxmega32c4}, @code{atxmega32d3}, @code{atxmega32d4}, @code{atxmega32e5}, @code{avr64da28}, @code{avr64da32}, @code{avr64da48}, @code{avr64da64}, @code{avr64db28}, @code{avr64db32}, @code{avr64db48}, @code{avr64db64}.
@item avrxmega3
``XMEGA'' devices with up to 64@tie{}KiB of combined program memory and RAM, and with program memory visible in the RAM address space.
@*@var{mcu}@tie{}= @code{attiny202}, @code{attiny204}, @code{attiny212}, @code{attiny214}, @code{attiny402}, @code{attiny404}, @code{attiny406}, @code{attiny412}, @code{attiny414}, @code{attiny416}, @code{attiny417}, @code{attiny804}, @code{attiny806}, @code{attiny807}, @code{attiny814}, @code{attiny816}, @code{attiny817}, @code{attiny1604}, @code{attiny1606}, @code{attiny1607}, @code{attiny1614}, @code{attiny1616}, @code{attiny1617}, @code{attiny3214}, @code{attiny3216}, @code{attiny3217}, @code{atmega808}, @code{atmega809}, @code{atmega1608}, @code{atmega1609}, @code{atmega3208}, @code{atmega3209}, @code{atmega4808}, @code{atmega4809}, @code{avr32da28}, @code{avr32da32}, @code{avr32da48}, @code{avr32db28}, @code{avr32db32}, @code{avr32db48}.
@item avrxmega4
``XMEGA'' devices with more than 64@tie{}KiB and up to 128@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{atxmega64a3}, @code{atxmega64a3u}, @code{atxmega64a4u}, @code{atxmega64b1}, @code{atxmega64b3}, @code{atxmega64c3}, @code{atxmega64d3}, @code{atxmega64d4}, @code{avr128da28}, @code{avr128da32}, @code{avr128da48}, @code{avr128da64}, @code{avr128db28}, @code{avr128db32}, @code{avr128db48}, @code{avr128db64}.
@item avrxmega5
``XMEGA'' devices with more than 64@tie{}KiB and up to 128@tie{}KiB of program memory and more than 64@tie{}KiB of RAM.
@*@var{mcu}@tie{}= @code{atxmega64a1}, @code{atxmega64a1u}.
@item avrxmega6
``XMEGA'' devices with more than 128@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{atxmega128a3}, @code{atxmega128a3u}, @code{atxmega128b1}, @code{atxmega128b3}, @code{atxmega128c3}, @code{atxmega128d3}, @code{atxmega128d4}, @code{atxmega192a3}, @code{atxmega192a3u}, @code{atxmega192c3}, @code{atxmega192d3}, @code{atxmega256a3}, @code{atxmega256a3b}, @code{atxmega256a3bu}, @code{atxmega256a3u}, @code{atxmega256c3}, @code{atxmega256d3}, @code{atxmega384c3}, @code{atxmega384d3}.
@item avrxmega7
``XMEGA'' devices with more than 128@tie{}KiB of program memory and more than 64@tie{}KiB of RAM.
@*@var{mcu}@tie{}= @code{atxmega128a1}, @code{atxmega128a1u}, @code{atxmega128a4u}.
@item avrtiny
``TINY'' Tiny core devices with 512@tie{}B up to 4@tie{}KiB of program memory.
@*@var{mcu}@tie{}= @code{attiny4}, @code{attiny5}, @code{attiny9}, @code{attiny10}, @code{attiny20}, @code{attiny40}.
@item avr1
This ISA is implemented by the minimal AVR core and supported for assembler only.
@*@var{mcu}@tie{}= @code{attiny11}, @code{attiny12}, @code{attiny15}, @code{attiny28}, @code{at90s1200}.
@end table

88
gcc/doc/bugreport.texi Normal file
View File

@ -0,0 +1,88 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Bugs
@chapter Reporting Bugs
@cindex bugs
@cindex reporting bugs
Your bug reports play an essential role in making GCC reliable.
When you encounter a problem, the first thing to do is to see if it is
already known. @xref{Trouble}. If it isn't known, then you should
report the problem.
@menu
* Criteria: Bug Criteria. Have you really found a bug?
* Reporting: Bug Reporting. How to report a bug effectively.
@end menu
@node Bug Criteria
@section Have You Found a Bug?
@cindex bug criteria
If you are not sure whether you have found a bug, here are some guidelines:
@itemize @bullet
@cindex fatal signal
@cindex core dump
@item
If the compiler gets a fatal signal, for any input whatever, that is a
compiler bug. Reliable compilers never crash.
@cindex invalid assembly code
@cindex assembly code, invalid
@item
If the compiler produces invalid assembly code, for any input whatever
(except an @code{asm} statement), that is a compiler bug, unless the
compiler reports errors (not just warnings) which would ordinarily
prevent the assembler from being run.
@cindex undefined behavior
@cindex undefined function value
@cindex increment operators
@item
If the compiler produces valid assembly code that does not correctly
execute the input source code, that is a compiler bug.
However, you must double-check to make sure, because you may have a
program whose behavior is undefined, which happened by chance to give
the desired results with another C or C++ compiler.
For example, in many nonoptimizing compilers, you can write @samp{x;}
at the end of a function instead of @samp{return x;}, with the same
results. But the value of the function is undefined if @code{return}
is omitted; it is not a bug when GCC produces different results.
Problems often result from expressions with two increment operators,
as in @code{f (*p++, *p++)}. Your previous compiler might have
interpreted that expression the way you intended; GCC might
interpret it another way. Neither compiler is wrong. The bug is
in your code.
After you have localized the error to a single source line, it should
be easy to check for these things. If your program is correct and
well defined, you have found a compiler bug.
@item
If the compiler produces an error message for valid input, that is a
compiler bug.
@cindex invalid input
@item
If the compiler does not produce an error message for invalid input,
that is a compiler bug. However, you should note that your idea of
``invalid input'' might be someone else's idea of ``an extension'' or
``support for traditional practice''.
@item
If you are an experienced user of one of the languages GCC supports, your
suggestions for improvement of GCC are welcome in any case.
@end itemize
@node Bug Reporting
@section How and Where to Report Bugs
@cindex compiler bugs, reporting
Bugs should be reported to the bug database at @value{BUGURL}.

684
gcc/doc/cfg.texi Normal file
View File

@ -0,0 +1,684 @@
@c -*-texinfo-*-
@c Copyright (C) 2001-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@c ---------------------------------------------------------------------
@c Control Flow Graph
@c ---------------------------------------------------------------------
@node Control Flow
@chapter Control Flow Graph
@cindex CFG, Control Flow Graph
@findex basic-block.h
A control flow graph (CFG) is a data structure built on top of the
intermediate code representation (the RTL or @code{GIMPLE} instruction
stream) abstracting the control flow behavior of a function that is
being compiled. The CFG is a directed graph where the vertices
represent basic blocks and edges represent possible transfer of
control flow from one basic block to another. The data structures
used to represent the control flow graph are defined in
@file{basic-block.h}.
In GCC, the representation of control flow is maintained throughout
the compilation process, from constructing the CFG early in
@code{pass_build_cfg} to @code{pass_free_cfg} (see @file{passes.def}).
The CFG takes various different modes and may undergo extensive
manipulations, but the graph is always valid between its construction
and its release. This way, transfer of information such as data flow,
a measured profile, or the loop tree, can be propagated through the
passes pipeline, and even from @code{GIMPLE} to @code{RTL}.
Often the CFG may be better viewed as integral part of instruction
chain, than structure built on the top of it. Updating the compiler's
intermediate representation for instructions cannot be easily done
without proper maintenance of the CFG simultaneously.
@menu
* Basic Blocks:: The definition and representation of basic blocks.
* Edges:: Types of edges and their representation.
* Profile information:: Representation of frequencies and probabilities.
* Maintaining the CFG:: Keeping the control flow graph and up to date.
* Liveness information:: Using and maintaining liveness information.
@end menu
@node Basic Blocks
@section Basic Blocks
@cindex basic block
@findex basic_block
A basic block is a straight-line sequence of code with only one entry
point and only one exit. In GCC, basic blocks are represented using
the @code{basic_block} data type.
@findex ENTRY_BLOCK_PTR, EXIT_BLOCK_PTR
Special basic blocks represent possible entry and exit points of a
function. These blocks are called @code{ENTRY_BLOCK_PTR} and
@code{EXIT_BLOCK_PTR}. These blocks do not contain any code.
@findex BASIC_BLOCK
The @code{BASIC_BLOCK} array contains all basic blocks in an
unspecified order. Each @code{basic_block} structure has a field
that holds a unique integer identifier @code{index} that is the
index of the block in the @code{BASIC_BLOCK} array.
The total number of basic blocks in the function is
@code{n_basic_blocks}. Both the basic block indices and
the total number of basic blocks may vary during the compilation
process, as passes reorder, create, duplicate, and destroy basic
blocks. The index for any block should never be greater than
@code{last_basic_block}. The indices 0 and 1 are special codes
reserved for @code{ENTRY_BLOCK} and @code{EXIT_BLOCK}, the
indices of @code{ENTRY_BLOCK_PTR} and @code{EXIT_BLOCK_PTR}.
@findex next_bb, prev_bb, FOR_EACH_BB, FOR_ALL_BB
Two pointer members of the @code{basic_block} structure are the
pointers @code{next_bb} and @code{prev_bb}. These are used to keep
doubly linked chain of basic blocks in the same order as the
underlying instruction stream. The chain of basic blocks is updated
transparently by the provided API for manipulating the CFG@. The macro
@code{FOR_EACH_BB} can be used to visit all the basic blocks in
lexicographical order, except @code{ENTRY_BLOCK} and @code{EXIT_BLOCK}.
The macro @code{FOR_ALL_BB} also visits all basic blocks in
lexicographical order, including @code{ENTRY_BLOCK} and @code{EXIT_BLOCK}.
@findex post_order_compute, inverted_post_order_compute, walk_dominator_tree
The functions @code{post_order_compute} and @code{inverted_post_order_compute}
can be used to compute topological orders of the CFG. The orders are
stored as vectors of basic block indices. The @code{BASIC_BLOCK} array
can be used to iterate each basic block by index.
Dominator traversals are also possible using
@code{walk_dominator_tree}. Given two basic blocks A and B, block A
dominates block B if A is @emph{always} executed before B@.
Each @code{basic_block} also contains pointers to the first
instruction (the @dfn{head}) and the last instruction (the @dfn{tail})
or @dfn{end} of the instruction stream contained in a basic block. In
fact, since the @code{basic_block} data type is used to represent
blocks in both major intermediate representations of GCC (@code{GIMPLE}
and RTL), there are pointers to the head and end of a basic block for
both representations, stored in intermediate representation specific
data in the @code{il} field of @code{struct basic_block_def}.
@findex CODE_LABEL
@findex NOTE_INSN_BASIC_BLOCK
For RTL, these pointers are @code{BB_HEAD} and @code{BB_END}.
@cindex insn notes, notes
@findex NOTE_INSN_BASIC_BLOCK
In the RTL representation of a function, the instruction stream
contains not only the ``real'' instructions, but also @dfn{notes}
or @dfn{insn notes} (to distinguish them from @dfn{reg notes}).
Any function that moves or duplicates the basic blocks needs
to take care of updating of these notes. Many of these notes expect
that the instruction stream consists of linear regions, so updating
can sometimes be tedious. All types of insn notes are defined
in @file{insn-notes.def}.
In the RTL function representation, the instructions contained in a
basic block always follow a @code{NOTE_INSN_BASIC_BLOCK}, but zero
or more @code{CODE_LABEL} nodes can precede the block note.
A basic block ends with a control flow instruction or with the last
instruction before the next @code{CODE_LABEL} or
@code{NOTE_INSN_BASIC_BLOCK}.
By definition, a @code{CODE_LABEL} cannot appear in the middle of
the instruction stream of a basic block.
@findex can_fallthru
@cindex table jump
In addition to notes, the jump table vectors are also represented as
``pseudo-instructions'' inside the insn stream. These vectors never
appear in the basic block and should always be placed just after the
table jump instructions referencing them. After removing the
table-jump it is often difficult to eliminate the code computing the
address and referencing the vector, so cleaning up these vectors is
postponed until after liveness analysis. Thus the jump table vectors
may appear in the insn stream unreferenced and without any purpose.
Before any edge is made @dfn{fall-thru}, the existence of such
construct in the way needs to be checked by calling
@code{can_fallthru} function.
@cindex GIMPLE statement iterators
For the @code{GIMPLE} representation, the PHI nodes and statements
contained in a basic block are in a @code{gimple_seq} pointed to by
the basic block intermediate language specific pointers.
Abstract containers and iterators are used to access the PHI nodes
and statements in a basic blocks. These iterators are called
@dfn{GIMPLE statement iterators} (GSIs). Grep for @code{^gsi}
in the various @file{gimple-*} and @file{tree-*} files.
There is a @code{gimple_stmt_iterator} type for iterating over
all kinds of statement, and a @code{gphi_iterator} subclass for
iterating over PHI nodes.
The following snippet will pretty-print all PHI nodes the statements
of the current function in the GIMPLE representation.
@smallexample
basic_block bb;
FOR_EACH_BB (bb)
@{
gphi_iterator pi;
gimple_stmt_iterator si;
for (pi = gsi_start_phis (bb); !gsi_end_p (pi); gsi_next (&pi))
@{
gphi *phi = pi.phi ();
print_gimple_stmt (dump_file, phi, 0, TDF_SLIM);
@}
for (si = gsi_start_bb (bb); !gsi_end_p (si); gsi_next (&si))
@{
gimple stmt = gsi_stmt (si);
print_gimple_stmt (dump_file, stmt, 0, TDF_SLIM);
@}
@}
@end smallexample
@node Edges
@section Edges
@cindex edge in the flow graph
@findex edge
Edges represent possible control flow transfers from the end of some
basic block A to the head of another basic block B@. We say that A is
a predecessor of B, and B is a successor of A@. Edges are represented
in GCC with the @code{edge} data type. Each @code{edge} acts as a
link between two basic blocks: The @code{src} member of an edge
points to the predecessor basic block of the @code{dest} basic block.
The members @code{preds} and @code{succs} of the @code{basic_block} data
type point to type-safe vectors of edges to the predecessors and
successors of the block.
@cindex edge iterators
When walking the edges in an edge vector, @dfn{edge iterators} should
be used. Edge iterators are constructed using the
@code{edge_iterator} data structure and several methods are available
to operate on them:
@ftable @code
@item ei_start
This function initializes an @code{edge_iterator} that points to the
first edge in a vector of edges.
@item ei_last
This function initializes an @code{edge_iterator} that points to the
last edge in a vector of edges.
@item ei_end_p
This predicate is @code{true} if an @code{edge_iterator} represents
the last edge in an edge vector.
@item ei_one_before_end_p
This predicate is @code{true} if an @code{edge_iterator} represents
the second last edge in an edge vector.
@item ei_next
This function takes a pointer to an @code{edge_iterator} and makes it
point to the next edge in the sequence.
@item ei_prev
This function takes a pointer to an @code{edge_iterator} and makes it
point to the previous edge in the sequence.
@item ei_edge
This function returns the @code{edge} currently pointed to by an
@code{edge_iterator}.
@item ei_safe_edge
This function returns the @code{edge} currently pointed to by an
@code{edge_iterator}, but returns @code{NULL} if the iterator is
pointing at the end of the sequence. This function has been provided
for existing code makes the assumption that a @code{NULL} edge
indicates the end of the sequence.
@end ftable
The convenience macro @code{FOR_EACH_EDGE} can be used to visit all of
the edges in a sequence of predecessor or successor edges. It must
not be used when an element might be removed during the traversal,
otherwise elements will be missed. Here is an example of how to use
the macro:
@smallexample
edge e;
edge_iterator ei;
FOR_EACH_EDGE (e, ei, bb->succs)
@{
if (e->flags & EDGE_FALLTHRU)
break;
@}
@end smallexample
@findex fall-thru
There are various reasons why control flow may transfer from one block
to another. One possibility is that some instruction, for example a
@code{CODE_LABEL}, in a linearized instruction stream just always
starts a new basic block. In this case a @dfn{fall-thru} edge links
the basic block to the first following basic block. But there are
several other reasons why edges may be created. The @code{flags}
field of the @code{edge} data type is used to store information
about the type of edge we are dealing with. Each edge is of one of
the following types:
@table @emph
@item jump
No type flags are set for edges corresponding to jump instructions.
These edges are used for unconditional or conditional jumps and in
RTL also for table jumps. They are the easiest to manipulate as they
may be freely redirected when the flow graph is not in SSA form.
@item fall-thru
@findex EDGE_FALLTHRU, force_nonfallthru
Fall-thru edges are present in case where the basic block may continue
execution to the following one without branching. These edges have
the @code{EDGE_FALLTHRU} flag set. Unlike other types of edges, these
edges must come into the basic block immediately following in the
instruction stream. The function @code{force_nonfallthru} is
available to insert an unconditional jump in the case that redirection
is needed. Note that this may require creation of a new basic block.
@item exception handling
@cindex exception handling
@findex EDGE_ABNORMAL, EDGE_EH
Exception handling edges represent possible control transfers from a
trapping instruction to an exception handler. The definition of
``trapping'' varies. In C++, only function calls can throw, but for
Ada exceptions like division by zero or segmentation fault are
defined and thus each instruction possibly throwing this kind of
exception needs to be handled as control flow instruction. Exception
edges have the @code{EDGE_ABNORMAL} and @code{EDGE_EH} flags set.
@findex purge_dead_edges
When updating the instruction stream it is easy to change possibly
trapping instruction to non-trapping, by simply removing the exception
edge. The opposite conversion is difficult, but should not happen
anyway. The edges can be eliminated via @code{purge_dead_edges} call.
@findex REG_EH_REGION, EDGE_ABNORMAL_CALL
In the RTL representation, the destination of an exception edge is
specified by @code{REG_EH_REGION} note attached to the insn.
In case of a trapping call the @code{EDGE_ABNORMAL_CALL} flag is set
too. In the @code{GIMPLE} representation, this extra flag is not set.
@findex may_trap_p, tree_could_trap_p
In the RTL representation, the predicate @code{may_trap_p} may be used
to check whether instruction still may trap or not. For the tree
representation, the @code{tree_could_trap_p} predicate is available,
but this predicate only checks for possible memory traps, as in
dereferencing an invalid pointer location.
@item sibling calls
@cindex sibling call
@findex EDGE_ABNORMAL, EDGE_SIBCALL
Sibling calls or tail calls terminate the function in a non-standard
way and thus an edge to the exit must be present.
@code{EDGE_SIBCALL} and @code{EDGE_ABNORMAL} are set in such case.
These edges only exist in the RTL representation.
@item computed jumps
@cindex computed jump
@findex EDGE_ABNORMAL
Computed jumps contain edges to all labels in the function referenced
from the code. All those edges have @code{EDGE_ABNORMAL} flag set.
The edges used to represent computed jumps often cause compile time
performance problems, since functions consisting of many taken labels
and many computed jumps may have @emph{very} dense flow graphs, so
these edges need to be handled with special care. During the earlier
stages of the compilation process, GCC tries to avoid such dense flow
graphs by factoring computed jumps. For example, given the following
series of jumps,
@smallexample
goto *x;
[ @dots{} ]
goto *x;
[ @dots{} ]
goto *x;
[ @dots{} ]
@end smallexample
@noindent
factoring the computed jumps results in the following code sequence
which has a much simpler flow graph:
@smallexample
goto y;
[ @dots{} ]
goto y;
[ @dots{} ]
goto y;
[ @dots{} ]
y:
goto *x;
@end smallexample
@findex pass_duplicate_computed_gotos
However, the classic problem with this transformation is that it has a
runtime cost in there resulting code: An extra jump. Therefore, the
computed jumps are un-factored in the later passes of the compiler
(in the pass called @code{pass_duplicate_computed_gotos}).
Be aware of that when you work on passes in that area. There have
been numerous examples already where the compile time for code with
unfactored computed jumps caused some serious headaches.
@item nonlocal goto handlers
@cindex nonlocal goto handler
@findex EDGE_ABNORMAL, EDGE_ABNORMAL_CALL
GCC allows nested functions to return into caller using a @code{goto}
to a label passed to as an argument to the callee. The labels passed
to nested functions contain special code to cleanup after function
call. Such sections of code are referred to as ``nonlocal goto
receivers''. If a function contains such nonlocal goto receivers, an
edge from the call to the label is created with the
@code{EDGE_ABNORMAL} and @code{EDGE_ABNORMAL_CALL} flags set.
@item function entry points
@cindex function entry point, alternate function entry point
@findex LABEL_ALTERNATE_NAME
By definition, execution of function starts at basic block 0, so there
is always an edge from the @code{ENTRY_BLOCK_PTR} to basic block 0.
There is no @code{GIMPLE} representation for alternate entry points at
this moment. In RTL, alternate entry points are specified by
@code{CODE_LABEL} with @code{LABEL_ALTERNATE_NAME} defined. This
feature is currently used for multiple entry point prologues and is
limited to post-reload passes only. This can be used by back-ends to
emit alternate prologues for functions called from different contexts.
In future full support for multiple entry functions defined by Fortran
90 needs to be implemented.
@item function exits
In the pre-reload representation a function terminates after the last
instruction in the insn chain and no explicit return instructions are
used. This corresponds to the fall-thru edge into exit block. After
reload, optimal RTL epilogues are used that use explicit (conditional)
return instructions that are represented by edges with no flags set.
@end table
@node Profile information
@section Profile information
@cindex profile representation
In many cases a compiler must make a choice whether to trade speed in
one part of code for speed in another, or to trade code size for code
speed. In such cases it is useful to know information about how often
some given block will be executed. That is the purpose for
maintaining profile within the flow graph.
GCC can handle profile information obtained through @dfn{profile
feedback}, but it can also estimate branch probabilities based on
statics and heuristics.
@cindex profile feedback
The feedback based profile is produced by compiling the program with
instrumentation, executing it on a train run and reading the numbers
of executions of basic blocks and edges back to the compiler while
re-compiling the program to produce the final executable. This method
provides very accurate information about where a program spends most
of its time on the train run. Whether it matches the average run of
course depends on the choice of train data set, but several studies
have shown that the behavior of a program usually changes just
marginally over different data sets.
@cindex Static profile estimation
@cindex branch prediction
@findex predict.def
When profile feedback is not available, the compiler may be asked to
attempt to predict the behavior of each branch in the program using a
set of heuristics (see @file{predict.def} for details) and compute
estimated frequencies of each basic block by propagating the
probabilities over the graph.
@findex frequency, count, BB_FREQ_BASE
Each @code{basic_block} contains two integer fields to represent
profile information: @code{frequency} and @code{count}. The
@code{frequency} is an estimation how often is basic block executed
within a function. It is represented as an integer scaled in the
range from 0 to @code{BB_FREQ_BASE}. The most frequently executed
basic block in function is initially set to @code{BB_FREQ_BASE} and
the rest of frequencies are scaled accordingly. During optimization,
the frequency of the most frequent basic block can both decrease (for
instance by loop unrolling) or grow (for instance by cross-jumping
optimization), so scaling sometimes has to be performed multiple
times.
@findex gcov_type
The @code{count} contains hard-counted numbers of execution measured
during training runs and is nonzero only when profile feedback is
available. This value is represented as the host's widest integer
(typically a 64 bit integer) of the special type @code{gcov_type}.
Most optimization passes can use only the frequency information of a
basic block, but a few passes may want to know hard execution counts.
The frequencies should always match the counts after scaling, however
during updating of the profile information numerical error may
accumulate into quite large errors.
@findex REG_BR_PROB_BASE, EDGE_FREQUENCY
Each edge also contains a branch probability field: an integer in the
range from 0 to @code{REG_BR_PROB_BASE}. It represents probability of
passing control from the end of the @code{src} basic block to the
@code{dest} basic block, i.e.@: the probability that control will flow
along this edge. The @code{EDGE_FREQUENCY} macro is available to
compute how frequently a given edge is taken. There is a @code{count}
field for each edge as well, representing same information as for a
basic block.
The basic block frequencies are not represented in the instruction
stream, but in the RTL representation the edge frequencies are
represented for conditional jumps (via the @code{REG_BR_PROB}
macro) since they are used when instructions are output to the
assembly file and the flow graph is no longer maintained.
@cindex reverse probability
The probability that control flow arrives via a given edge to its
destination basic block is called @dfn{reverse probability} and is not
directly represented, but it may be easily computed from frequencies
of basic blocks.
@findex redirect_edge_and_branch
Updating profile information is a delicate task that can unfortunately
not be easily integrated with the CFG manipulation API@. Many of the
functions and hooks to modify the CFG, such as
@code{redirect_edge_and_branch}, do not have enough information to
easily update the profile, so updating it is in the majority of cases
left up to the caller. It is difficult to uncover bugs in the profile
updating code, because they manifest themselves only by producing
worse code, and checking profile consistency is not possible because
of numeric error accumulation. Hence special attention needs to be
given to this issue in each pass that modifies the CFG@.
@findex REG_BR_PROB_BASE, BB_FREQ_BASE, count
It is important to point out that @code{REG_BR_PROB_BASE} and
@code{BB_FREQ_BASE} are both set low enough to be possible to compute
second power of any frequency or probability in the flow graph, it is
not possible to even square the @code{count} field, as modern CPUs are
fast enough to execute $2^32$ operations quickly.
@node Maintaining the CFG
@section Maintaining the CFG
@findex cfghooks.h
An important task of each compiler pass is to keep both the control
flow graph and all profile information up-to-date. Reconstruction of
the control flow graph after each pass is not an option, since it may be
very expensive and lost profile information cannot be reconstructed at
all.
GCC has two major intermediate representations, and both use the
@code{basic_block} and @code{edge} data types to represent control
flow. Both representations share as much of the CFG maintenance code
as possible. For each representation, a set of @dfn{hooks} is defined
so that each representation can provide its own implementation of CFG
manipulation routines when necessary. These hooks are defined in
@file{cfghooks.h}. There are hooks for almost all common CFG
manipulations, including block splitting and merging, edge redirection
and creating and deleting basic blocks. These hooks should provide
everything you need to maintain and manipulate the CFG in both the RTL
and @code{GIMPLE} representation.
At the moment, the basic block boundaries are maintained transparently
when modifying instructions, so there rarely is a need to move them
manually (such as in case someone wants to output instruction outside
basic block explicitly).
@findex BLOCK_FOR_INSN, gimple_bb
In the RTL representation, each instruction has a
@code{BLOCK_FOR_INSN} value that represents pointer to the basic block
that contains the instruction. In the @code{GIMPLE} representation, the
function @code{gimple_bb} returns a pointer to the basic block
containing the queried statement.
@cindex GIMPLE statement iterators
When changes need to be applied to a function in its @code{GIMPLE}
representation, @dfn{GIMPLE statement iterators} should be used. These
iterators provide an integrated abstraction of the flow graph and the
instruction stream. Block statement iterators are constructed using
the @code{gimple_stmt_iterator} data structure and several modifiers are
available, including the following:
@ftable @code
@item gsi_start
This function initializes a @code{gimple_stmt_iterator} that points to
the first non-empty statement in a basic block.
@item gsi_last
This function initializes a @code{gimple_stmt_iterator} that points to
the last statement in a basic block.
@item gsi_end_p
This predicate is @code{true} if a @code{gimple_stmt_iterator}
represents the end of a basic block.
@item gsi_next
This function takes a @code{gimple_stmt_iterator} and makes it point to
its successor.
@item gsi_prev
This function takes a @code{gimple_stmt_iterator} and makes it point to
its predecessor.
@item gsi_insert_after
This function inserts a statement after the @code{gimple_stmt_iterator}
passed in. The final parameter determines whether the statement
iterator is updated to point to the newly inserted statement, or left
pointing to the original statement.
@item gsi_insert_before
This function inserts a statement before the @code{gimple_stmt_iterator}
passed in. The final parameter determines whether the statement
iterator is updated to point to the newly inserted statement, or left
pointing to the original statement.
@item gsi_remove
This function removes the @code{gimple_stmt_iterator} passed in and
rechains the remaining statements in a basic block, if any.
@end ftable
@findex BB_HEAD, BB_END
In the RTL representation, the macros @code{BB_HEAD} and @code{BB_END}
may be used to get the head and end @code{rtx} of a basic block. No
abstract iterators are defined for traversing the insn chain, but you
can just use @code{NEXT_INSN} and @code{PREV_INSN} instead. @xref{Insns}.
@findex purge_dead_edges
Usually a code manipulating pass simplifies the instruction stream and
the flow of control, possibly eliminating some edges. This may for
example happen when a conditional jump is replaced with an
unconditional jump. Updating of edges
is not transparent and each optimization pass is required to do so
manually. However only few cases occur in practice. The pass may
call @code{purge_dead_edges} on a given basic block to remove
superfluous edges, if any.
@findex redirect_edge_and_branch, redirect_jump
Another common scenario is redirection of branch instructions, but
this is best modeled as redirection of edges in the control flow graph
and thus use of @code{redirect_edge_and_branch} is preferred over more
low level functions, such as @code{redirect_jump} that operate on RTL
chain only. The CFG hooks defined in @file{cfghooks.h} should provide
the complete API required for manipulating and maintaining the CFG@.
@findex split_block
It is also possible that a pass has to insert control flow instruction
into the middle of a basic block, thus creating an entry point in the
middle of the basic block, which is impossible by definition: The
block must be split to make sure it only has one entry point, i.e.@: the
head of the basic block. The CFG hook @code{split_block} may be used
when an instruction in the middle of a basic block has to become the
target of a jump or branch instruction.
@findex insert_insn_on_edge
@findex commit_edge_insertions
@findex gsi_insert_on_edge
@findex gsi_commit_edge_inserts
@cindex edge splitting
For a global optimizer, a common operation is to split edges in the
flow graph and insert instructions on them. In the RTL
representation, this can be easily done using the
@code{insert_insn_on_edge} function that emits an instruction
``on the edge'', caching it for a later @code{commit_edge_insertions}
call that will take care of moving the inserted instructions off the
edge into the instruction stream contained in a basic block. This
includes the creation of new basic blocks where needed. In the
@code{GIMPLE} representation, the equivalent functions are
@code{gsi_insert_on_edge} which inserts a block statement
iterator on an edge, and @code{gsi_commit_edge_inserts} which flushes
the instruction to actual instruction stream.
@findex verify_flow_info
@cindex CFG verification
While debugging the optimization pass, the @code{verify_flow_info}
function may be useful to find bugs in the control flow graph updating
code.
@node Liveness information
@section Liveness information
@cindex Liveness representation
Liveness information is useful to determine whether some register is
``live'' at given point of program, i.e.@: that it contains a value that
may be used at a later point in the program. This information is
used, for instance, during register allocation, as the pseudo
registers only need to be assigned to a unique hard register or to a
stack slot if they are live. The hard registers and stack slots may
be freely reused for other values when a register is dead.
Liveness information is available in the back end starting with
@code{pass_df_initialize} and ending with @code{pass_df_finish}. Three
flavors of live analysis are available: With @code{LR}, it is possible
to determine at any point @code{P} in the function if the register may be
used on some path from @code{P} to the end of the function. With
@code{UR}, it is possible to determine if there is a path from the
beginning of the function to @code{P} that defines the variable.
@code{LIVE} is the intersection of the @code{LR} and @code{UR} and a
variable is live at @code{P} if there is both an assignment that reaches
it from the beginning of the function and a use that can be reached on
some path from @code{P} to the end of the function.
In general @code{LIVE} is the most useful of the three. The macros
@code{DF_[LR,UR,LIVE]_[IN,OUT]} can be used to access this information.
The macros take a basic block number and return a bitmap that is indexed
by the register number. This information is only guaranteed to be up to
date after calls are made to @code{df_analyze}. See the file
@code{df-core.cc} for details on using the dataflow.
@findex REG_DEAD, REG_UNUSED
The liveness information is stored partly in the RTL instruction stream
and partly in the flow graph. Local information is stored in the
instruction stream: Each instruction may contain @code{REG_DEAD} notes
representing that the value of a given register is no longer needed, or
@code{REG_UNUSED} notes representing that the value computed by the
instruction is never used. The second is useful for instructions
computing multiple values at once.

89
gcc/doc/collect2.texi Normal file
View File

@ -0,0 +1,89 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Collect2
@chapter @code{collect2}
GCC uses a utility called @code{collect2} on nearly all systems to arrange
to call various initialization functions at start time.
The program @code{collect2} works by linking the program once and
looking through the linker output file for symbols with particular names
indicating they are constructor functions. If it finds any, it
creates a new temporary @samp{.c} file containing a table of them,
compiles it, and links the program a second time including that file.
@findex __main
@cindex constructors, automatic calls
The actual calls to the constructors are carried out by a subroutine
called @code{__main}, which is called (automatically) at the beginning
of the body of @code{main} (provided @code{main} was compiled with GNU
CC)@. Calling @code{__main} is necessary, even when compiling C code, to
allow linking C and C++ object code together. (If you use
@option{-nostdlib}, you get an unresolved reference to @code{__main},
since it's defined in the standard GCC library. Include @option{-lgcc} at
the end of your compiler command line to resolve this reference.)
The program @code{collect2} is installed as @code{ld} in the directory
where the passes of the compiler are installed. When @code{collect2}
needs to find the @emph{real} @code{ld}, it tries the following file
names:
@itemize @bullet
@item
a hard coded linker file name, if GCC was configured with the
@option{--with-ld} option.
@item
@file{real-ld} in the directories listed in the compiler's search
directories.
@item
@file{real-ld} in the directories listed in the environment variable
@code{PATH}.
@item
The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
if specified.
@item
@file{ld} in the compiler's search directories, except that
@code{collect2} will not execute itself recursively.
@item
@file{ld} in @code{PATH}.
@end itemize
``The compiler's search directories'' means all the directories where
@command{gcc} searches for passes of the compiler. This includes
directories that you specify with @option{-B}.
Cross-compilers search a little differently:
@itemize @bullet
@item
@file{real-ld} in the compiler's search directories.
@item
@file{@var{target}-real-ld} in @code{PATH}.
@item
The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
if specified.
@item
@file{ld} in the compiler's search directories.
@item
@file{@var{target}-ld} in @code{PATH}.
@end itemize
@code{collect2} explicitly avoids running @code{ld} using the file name
under which @code{collect2} itself was invoked. In fact, it remembers
up a list of such names---in case one copy of @code{collect2} finds
another copy (or version) of @code{collect2} installed as @code{ld} in a
second place in the search path.
@code{collect2} searches for the utilities @code{nm} and @code{strip}
using the same algorithm as above for @code{ld}.

156
gcc/doc/compat.texi Normal file
View File

@ -0,0 +1,156 @@
@c Copyright (C) 2002-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Compatibility
@chapter Binary Compatibility
@cindex binary compatibility
@cindex ABI
@cindex application binary interface
Binary compatibility encompasses several related concepts:
@table @dfn
@item application binary interface (ABI)
The set of runtime conventions followed by all of the tools that deal
with binary representations of a program, including compilers, assemblers,
linkers, and language runtime support.
Some ABIs are formal with a written specification, possibly designed
by multiple interested parties. Others are simply the way things are
actually done by a particular set of tools.
@item ABI conformance
A compiler conforms to an ABI if it generates code that follows all of
the specifications enumerated by that ABI@.
A library conforms to an ABI if it is implemented according to that ABI@.
An application conforms to an ABI if it is built using tools that conform
to that ABI and does not contain source code that specifically changes
behavior specified by the ABI@.
@item calling conventions
Calling conventions are a subset of an ABI that specify of how arguments
are passed and function results are returned.
@item interoperability
Different sets of tools are interoperable if they generate files that
can be used in the same program. The set of tools includes compilers,
assemblers, linkers, libraries, header files, startup files, and debuggers.
Binaries produced by different sets of tools are not interoperable unless
they implement the same ABI@. This applies to different versions of the
same tools as well as tools from different vendors.
@item intercallability
Whether a function in a binary built by one set of tools can call a
function in a binary built by a different set of tools is a subset
of interoperability.
@item implementation-defined features
Language standards include lists of implementation-defined features whose
behavior can vary from one implementation to another. Some of these
features are normally covered by a platform's ABI and others are not.
The features that are not covered by an ABI generally affect how a
program behaves, but not intercallability.
@item compatibility
Conformance to the same ABI and the same behavior of implementation-defined
features are both relevant for compatibility.
@end table
The application binary interface implemented by a C or C++ compiler
affects code generation and runtime support for:
@itemize @bullet
@item
size and alignment of data types
@item
layout of structured types
@item
calling conventions
@item
register usage conventions
@item
interfaces for runtime arithmetic support
@item
object file formats
@end itemize
In addition, the application binary interface implemented by a C++ compiler
affects code generation and runtime support for:
@itemize @bullet
@item
name mangling
@item
exception handling
@item
invoking constructors and destructors
@item
layout, alignment, and padding of classes
@item
layout and alignment of virtual tables
@end itemize
Some GCC compilation options cause the compiler to generate code that
does not conform to the platform's default ABI@. Other options cause
different program behavior for implementation-defined features that are
not covered by an ABI@. These options are provided for consistency with
other compilers that do not follow the platform's default ABI or the
usual behavior of implementation-defined features for the platform.
Be very careful about using such options.
Most platforms have a well-defined ABI that covers C code, but ABIs
that cover C++ functionality are not yet common.
Starting with GCC 3.2, GCC binary conventions for C++ are based on a
written, vendor-neutral C++ ABI that was designed to be specific to
64-bit Itanium but also includes generic specifications that apply to
any platform.
This C++ ABI is also implemented by other compiler vendors on some
platforms, notably GNU/Linux and BSD systems.
We have tried hard to provide a stable ABI that will be compatible with
future GCC releases, but it is possible that we will encounter problems
that make this difficult. Such problems could include different
interpretations of the C++ ABI by different vendors, bugs in the ABI, or
bugs in the implementation of the ABI in different compilers.
GCC's @option{-Wabi} switch warns when G++ generates code that is
probably not compatible with the C++ ABI@.
The C++ library used with a C++ compiler includes the Standard C++
Library, with functionality defined in the C++ Standard, plus language
runtime support. The runtime support is included in a C++ ABI, but there
is no formal ABI for the Standard C++ Library. Two implementations
of that library are interoperable if one follows the de-facto ABI of the
other and if they are both built with the same compiler, or with compilers
that conform to the same ABI for C++ compiler and runtime support.
When G++ and another C++ compiler conform to the same C++ ABI, but the
implementations of the Standard C++ Library that they normally use do not
follow the same ABI for the Standard C++ Library, object files built with
those compilers can be used in the same program only if they use the same
C++ library. This requires specifying the location of the C++ library
header files when invoking the compiler whose usual library is not being
used. The location of GCC's C++ header files depends on how the GCC
build was configured, but can be seen by using the G++ @option{-v} option.
With default configuration options for G++ 3.3 the compile line for a
different C++ compiler needs to include
@smallexample
-I@var{gcc_install_directory}/include/c++/3.3
@end smallexample
Similarly, compiling code with G++ that must use a C++ library other
than the GNU C++ library requires specifying the location of the header
files for that other library.
The most straightforward way to link a program to use a particular
C++ library is to use a C++ driver that specifies that C++ library by
default. The @command{g++} driver, for example, tells the linker where
to find GCC's C++ library (@file{libstdc++}) plus the other libraries
and startup files it needs, in the proper order.
If a program must use a different C++ library and it's not possible
to do the final link using a C++ driver that uses that library by default,
it is necessary to tell @command{g++} the location and name of that
library. It might also be necessary to specify different startup files
and other runtime support libraries, and to suppress the use of GCC's
support libraries with one or more of the options @option{-nostdlib},
@option{-nostartfiles}, and @option{-nodefaultlibs}.

69
gcc/doc/configfiles.texi Normal file
View File

@ -0,0 +1,69 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Configuration Files
@subsubsection Files Created by @code{configure}
Here we spell out what files will be set up by @file{configure} in the
@file{gcc} directory. Some other files are created as temporary files
in the configuration process, and are not used in the subsequent
build; these are not documented.
@itemize @bullet
@item
@file{Makefile} is constructed from @file{Makefile.in}, together with
the host and target fragments (@pxref{Fragments, , Makefile
Fragments}) @file{t-@var{target}} and @file{x-@var{host}} from
@file{config}, if any, and language Makefile fragments
@file{@var{language}/Make-lang.in}.
@item
@file{auto-host.h} contains information about the host machine
determined by @file{configure}. If the host machine is different from
the build machine, then @file{auto-build.h} is also created,
containing such information about the build machine.
@item
@file{config.status} is a script that may be run to recreate the
current configuration.
@item
@file{configargs.h} is a header containing details of the arguments
passed to @file{configure} to configure GCC, and of the thread model
used.
@item
@file{cstamp-h} is used as a timestamp.
@item
If a language @file{config-lang.in} file (@pxref{Front End Config, ,
The Front End @file{config-lang.in} File}) sets @code{outputs}, then
the files listed in @code{outputs} there are also generated.
@end itemize
The following configuration headers are created from the Makefile,
using @file{mkconfig.sh}, rather than directly by @file{configure}.
@file{config.h}, @file{bconfig.h} and @file{tconfig.h} all contain the
@file{xm-@var{machine}.h} header, if any, appropriate to the host,
build and target machines respectively, the configuration headers for
the target, and some definitions; for the host and build machines,
these include the autoconfigured headers generated by
@file{configure}. The other configuration headers are determined by
@file{config.gcc}. They also contain the typedefs for @code{rtx},
@code{rtvec} and @code{tree}.
@itemize @bullet
@item
@file{config.h}, for use in programs that run on the host machine.
@item
@file{bconfig.h}, for use in programs that run on the build machine.
@item
@file{tconfig.h}, for use in programs and libraries for the target
machine.
@item
@file{tm_p.h}, which includes the header @file{@var{machine}-protos.h}
that contains prototypes for functions in the target
@file{@var{machine}.c} file. The
@file{@var{machine}-protos.h} header is included after the @file{rtl.h}
and/or @file{tree.h} would have been included.
The @file{tm_p.h} also
includes the header @file{tm-preds.h} which is generated by
@file{genpreds} program during the build to define the declarations
and inline functions for the predicate functions.
@end itemize

61
gcc/doc/configterms.texi Normal file
View File

@ -0,0 +1,61 @@
@c Copyright (C) 2001-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Configure Terms
@section Configure Terms and History
@cindex configure terms
@cindex canadian
The configure and build process has a long and colorful history, and can
be confusing to anyone who doesn't know why things are the way they are.
While there are other documents which describe the configuration process
in detail, here are a few things that everyone working on GCC should
know.
There are three system names that the build knows about: the machine you
are building on (@dfn{build}), the machine that you are building for
(@dfn{host}), and the machine that GCC will produce code for
(@dfn{target}). When you configure GCC, you specify these with
@option{--build=}, @option{--host=}, and @option{--target=}.
Specifying the host without specifying the build should be avoided, as
@command{configure} may (and once did) assume that the host you specify
is also the build, which may not be true.
If build, host, and target are all the same, this is called a
@dfn{native}. If build and host are the same but target is different,
this is called a @dfn{cross}. If build, host, and target are all
different this is called a @dfn{canadian} (for obscure reasons dealing
with Canada's political party and the background of the person working
on the build at that time). If host and target are the same, but build
is different, you are using a cross-compiler to build a native for a
different system. Some people call this a @dfn{host-x-host},
@dfn{crossed native}, or @dfn{cross-built native}. If build and target
are the same, but host is different, you are using a cross compiler to
build a cross compiler that produces code for the machine you're
building on. This is rare, so there is no common way of describing it.
There is a proposal to call this a @dfn{crossback}.
If build and host are the same, the GCC you are building will also be
used to build the target libraries (like @code{libstdc++}). If build and host
are different, you must have already built and installed a cross
compiler that will be used to build the target libraries (if you
configured with @option{--target=foo-bar}, this compiler will be called
@command{foo-bar-gcc}).
In the case of target libraries, the machine you're building for is the
machine you specified with @option{--target}. So, build is the machine
you're building on (no change there), host is the machine you're
building for (the target libraries are built for the target, so host is
the target you specified), and target doesn't apply (because you're not
building a compiler, you're building libraries). The configure/make
process will adjust these variables as needed. It also sets
@code{$with_cross_host} to the original @option{--host} value in case you
need it.
The @code{libiberty} support library is built up to three times: once
for the host, once for the target (even if they are the same), and once
for the build if build and host are different. This allows it to be
used by all programs which are generated in the course of the build
process.

1776
gcc/doc/contrib.texi Normal file
View File

File diff suppressed because it is too large Load Diff

24
gcc/doc/contribute.texi Normal file
View File

@ -0,0 +1,24 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Contributing
@chapter Contributing to GCC Development
If you would like to help pretest GCC releases to assure they work well,
current development sources are available via Git (see
@uref{https://gcc.gnu.org/git.html}). Source and binary snapshots are
also available for FTP; see @uref{https://gcc.gnu.org/snapshots.html}.
If you would like to work on improvements to GCC, please read the
advice at these URLs:
@smallexample
@uref{https://gcc.gnu.org/contribute.html}
@uref{https://gcc.gnu.org/contributewhy.html}
@end smallexample
@noindent
for information on how to make useful contributions and avoid
duplication of effort. Suggested projects are listed at
@uref{https://gcc.gnu.org/projects/}.

4600
gcc/doc/cpp.texi Normal file
View File

File diff suppressed because it is too large Load Diff

154
gcc/doc/cppdiropts.texi Normal file
View File

@ -0,0 +1,154 @@
@c Copyright (C) 1999-2022 Free Software Foundation, Inc.
@c This is part of the CPP and GCC manuals.
@c For copying conditions, see the file gcc.texi.
@c ---------------------------------------------------------------------
@c Options affecting include directory search in the preprocessor
@c ---------------------------------------------------------------------
@c If this file is included with the flag ``cppmanual'' set, it is
@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
@item -I @var{dir}
@itemx -iquote @var{dir}
@itemx -isystem @var{dir}
@itemx -idirafter @var{dir}
@opindex I
@opindex iquote
@opindex isystem
@opindex idirafter
Add the directory @var{dir} to the list of directories to be searched
for header files during preprocessing.
@ifset cppmanual
@xref{Search Path}.
@end ifset
If @var{dir} begins with @samp{=} or @code{$SYSROOT}, then the @samp{=}
or @code{$SYSROOT} is replaced by the sysroot prefix; see
@option{--sysroot} and @option{-isysroot}.
Directories specified with @option{-iquote} apply only to the quote
form of the directive, @code{@w{#include "@var{file}"}}.
Directories specified with @option{-I}, @option{-isystem},
or @option{-idirafter} apply to lookup for both the
@code{@w{#include "@var{file}"}} and
@code{@w{#include <@var{file}>}} directives.
You can specify any number or combination of these options on the
command line to search for header files in several directories.
The lookup order is as follows:
@enumerate
@item
For the quote form of the include directive, the directory of the current
file is searched first.
@item
For the quote form of the include directive, the directories specified
by @option{-iquote} options are searched in left-to-right order,
as they appear on the command line.
@item
Directories specified with @option{-I} options are scanned in
left-to-right order.
@item
Directories specified with @option{-isystem} options are scanned in
left-to-right order.
@item
Standard system directories are scanned.
@item
Directories specified with @option{-idirafter} options are scanned in
left-to-right order.
@end enumerate
You can use @option{-I} to override a system header
file, substituting your own version, since these directories are
searched before the standard system header file directories.
However, you should
not use this option to add directories that contain vendor-supplied
system header files; use @option{-isystem} for that.
The @option{-isystem} and @option{-idirafter} options also mark the directory
as a system directory, so that it gets the same special treatment that
is applied to the standard system directories.
@ifset cppmanual
@xref{System Headers}.
@end ifset
If a standard system include directory, or a directory specified with
@option{-isystem}, is also specified with @option{-I}, the @option{-I}
option is ignored. The directory is still searched but as a
system directory at its normal position in the system include chain.
This is to ensure that GCC's procedure to fix buggy system headers and
the ordering for the @code{#include_next} directive are not inadvertently
changed.
If you really need to change the search order for system directories,
use the @option{-nostdinc} and/or @option{-isystem} options.
@ifset cppmanual
@xref{System Headers}.
@end ifset
@item -I-
@opindex I-
Split the include path.
This option has been deprecated. Please use @option{-iquote} instead for
@option{-I} directories before the @option{-I-} and remove the @option{-I-}
option.
Any directories specified with @option{-I}
options before @option{-I-} are searched only for headers requested with
@code{@w{#include "@var{file}"}}; they are not searched for
@code{@w{#include <@var{file}>}}. If additional directories are
specified with @option{-I} options after the @option{-I-}, those
directories are searched for all @samp{#include} directives.
In addition, @option{-I-} inhibits the use of the directory of the current
file directory as the first search directory for @code{@w{#include
"@var{file}"}}. There is no way to override this effect of @option{-I-}.
@ifset cppmanual
@xref{Search Path}.
@end ifset
@item -iprefix @var{prefix}
@opindex iprefix
Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
options. If the prefix represents a directory, you should include the
final @samp{/}.
@item -iwithprefix @var{dir}
@itemx -iwithprefixbefore @var{dir}
@opindex iwithprefix
@opindex iwithprefixbefore
Append @var{dir} to the prefix specified previously with
@option{-iprefix}, and add the resulting directory to the include search
path. @option{-iwithprefixbefore} puts it in the same place @option{-I}
would; @option{-iwithprefix} puts it where @option{-idirafter} would.
@item -isysroot @var{dir}
@opindex isysroot
This option is like the @option{--sysroot} option, but applies only to
header files (except for Darwin targets, where it applies to both header
files and libraries). See the @option{--sysroot} option for more
information.
@item -imultilib @var{dir}
@opindex imultilib
Use @var{dir} as a subdirectory of the directory containing
target-specific C++ headers.
@item -nostdinc
@opindex nostdinc
Do not search the standard system directories for header files.
Only the directories explicitly specified with @option{-I},
@option{-iquote}, @option{-isystem}, and/or @option{-idirafter}
options (and the directory of the current file, if appropriate)
are searched.
@item -nostdinc++
@opindex nostdinc++
Do not search for header files in the C++-specific standard directories,
but do still search the other standard directories. (This option is
used when building the C++ library.)

99
gcc/doc/cppenv.texi Normal file
View File

@ -0,0 +1,99 @@
@c Copyright (C) 1999-2022 Free Software Foundation, Inc.
@c This is part of the CPP and GCC manuals.
@c For copying conditions, see the file gcc.texi.
@c ---------------------------------------------------------------------
@c Environment variables affecting the preprocessor
@c ---------------------------------------------------------------------
@c If this file is included with the flag ``cppmanual'' set, it is
@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
@vtable @env
@item CPATH
@itemx C_INCLUDE_PATH
@itemx CPLUS_INCLUDE_PATH
@itemx OBJC_INCLUDE_PATH
@c Commented out until ObjC++ is part of GCC:
@c @itemx OBJCPLUS_INCLUDE_PATH
Each variable's value is a list of directories separated by a special
character, much like @env{PATH}, in which to look for header files.
The special character, @code{PATH_SEPARATOR}, is target-dependent and
determined at GCC build time. For Microsoft Windows-based targets it is a
semicolon, and for almost all other targets it is a colon.
@env{CPATH} specifies a list of directories to be searched as if
specified with @option{-I}, but after any paths given with @option{-I}
options on the command line. This environment variable is used
regardless of which language is being preprocessed.
The remaining environment variables apply only when preprocessing the
particular language indicated. Each specifies a list of directories
to be searched as if specified with @option{-isystem}, but after any
paths given with @option{-isystem} options on the command line.
In all these variables, an empty element instructs the compiler to
search its current working directory. Empty elements can appear at the
beginning or end of a path. For instance, if the value of
@env{CPATH} is @code{:/special/include}, that has the same
effect as @samp{@w{-I. -I/special/include}}.
@c man end
@ifset cppmanual
See also @ref{Search Path}.
@end ifset
@c man begin ENVIRONMENT
@item DEPENDENCIES_OUTPUT
@cindex dependencies for make as output
If this variable is set, its value specifies how to output
dependencies for Make based on the non-system header files processed
by the compiler. System header files are ignored in the dependency
output.
The value of @env{DEPENDENCIES_OUTPUT} can be just a file name, in
which case the Make rules are written to that file, guessing the target
name from the source file name. Or the value can have the form
@samp{@var{file} @var{target}}, in which case the rules are written to
file @var{file} using @var{target} as the target name.
In other words, this environment variable is equivalent to combining
the options @option{-MM} and @option{-MF}
@ifset cppmanual
(@pxref{Invocation}),
@end ifset
@ifclear cppmanual
(@pxref{Preprocessor Options}),
@end ifclear
with an optional @option{-MT} switch too.
@item SUNPRO_DEPENDENCIES
@cindex dependencies for make as output
This variable is the same as @env{DEPENDENCIES_OUTPUT} (see above),
except that system header files are not ignored, so it implies
@option{-M} rather than @option{-MM}. However, the dependence on the
main input file is omitted.
@ifset cppmanual
@xref{Invocation}.
@end ifset
@ifclear cppmanual
@xref{Preprocessor Options}.
@end ifclear
@item SOURCE_DATE_EPOCH
If this variable is set, its value specifies a UNIX timestamp to be
used in replacement of the current date and time in the @code{__DATE__}
and @code{__TIME__} macros, so that the embedded timestamps become
reproducible.
The value of @env{SOURCE_DATE_EPOCH} must be a UNIX timestamp,
defined as the number of seconds (excluding leap seconds) since
01 Jan 1970 00:00:00 represented in ASCII; identical to the output of
@code{date +%s} on GNU/Linux and other systems that support the
@code{%s} extension in the @code{date} command.
The value should be a known timestamp such as the last modification
time of the source or package and it should be set by the build
process.
@end vtable

1066
gcc/doc/cppinternals.texi Normal file
View File

File diff suppressed because it is too large Load Diff

557
gcc/doc/cppopts.texi Normal file
View File

@ -0,0 +1,557 @@
@c Copyright (C) 1999-2022 Free Software Foundation, Inc.
@c This is part of the CPP and GCC manuals.
@c For copying conditions, see the file gcc.texi.
@c ---------------------------------------------------------------------
@c Options affecting the preprocessor
@c ---------------------------------------------------------------------
@c If this file is included with the flag ``cppmanual'' set, it is
@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
@item -D @var{name}
@opindex D
Predefine @var{name} as a macro, with definition @code{1}.
@item -D @var{name}=@var{definition}
The contents of @var{definition} are tokenized and processed as if
they appeared during translation phase three in a @samp{#define}
directive. In particular, the definition is truncated by
embedded newline characters.
If you are invoking the preprocessor from a shell or shell-like
program you may need to use the shell's quoting syntax to protect
characters such as spaces that have a meaning in the shell syntax.
If you wish to define a function-like macro on the command line, write
its argument list with surrounding parentheses before the equals sign
(if any). Parentheses are meaningful to most shells, so you should
quote the option. With @command{sh} and @command{csh},
@option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works.
@option{-D} and @option{-U} options are processed in the order they
are given on the command line. All @option{-imacros @var{file}} and
@option{-include @var{file}} options are processed after all
@option{-D} and @option{-U} options.
@item -U @var{name}
@opindex U
Cancel any previous definition of @var{name}, either built in or
provided with a @option{-D} option.
@item -include @var{file}
@opindex include
Process @var{file} as if @code{#include "file"} appeared as the first
line of the primary source file. However, the first directory searched
for @var{file} is the preprocessor's working directory @emph{instead of}
the directory containing the main source file. If not found there, it
is searched for in the remainder of the @code{#include "@dots{}"} search
chain as normal.
If multiple @option{-include} options are given, the files are included
in the order they appear on the command line.
@item -imacros @var{file}
@opindex imacros
Exactly like @option{-include}, except that any output produced by
scanning @var{file} is thrown away. Macros it defines remain defined.
This allows you to acquire all the macros from a header without also
processing its declarations.
All files specified by @option{-imacros} are processed before all files
specified by @option{-include}.
@item -undef
@opindex undef
Do not predefine any system-specific or GCC-specific macros. The
standard predefined macros remain defined.
@ifset cppmanual
@xref{Standard Predefined Macros}.
@end ifset
@item -pthread
@opindex pthread
Define additional macros required for using the POSIX threads library.
You should use this option consistently for both compilation and linking.
This option is supported on GNU/Linux targets, most other Unix derivatives,
and also on x86 Cygwin and MinGW targets.
@item -M
@opindex M
@cindex @command{make}
@cindex dependencies, @command{make}
Instead of outputting the result of preprocessing, output a rule
suitable for @command{make} describing the dependencies of the main
source file. The preprocessor outputs one @command{make} rule containing
the object file name for that source file, a colon, and the names of all
the included files, including those coming from @option{-include} or
@option{-imacros} command-line options.
Unless specified explicitly (with @option{-MT} or @option{-MQ}), the
object file name consists of the name of the source file with any
suffix replaced with object file suffix and with any leading directory
parts removed. If there are many included files then the rule is
split into several lines using @samp{\}-newline. The rule has no
commands.
This option does not suppress the preprocessor's debug output, such as
@option{-dM}. To avoid mixing such debug output with the dependency
rules you should explicitly specify the dependency output file with
@option{-MF}, or use an environment variable like
@env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}). Debug output
is still sent to the regular output stream as normal.
Passing @option{-M} to the driver implies @option{-E}, and suppresses
warnings with an implicit @option{-w}.
@item -MM
@opindex MM
Like @option{-M} but do not mention header files that are found in
system header directories, nor header files that are included,
directly or indirectly, from such a header.
This implies that the choice of angle brackets or double quotes in an
@samp{#include} directive does not in itself determine whether that
header appears in @option{-MM} dependency output.
@anchor{dashMF}
@item -MF @var{file}
@opindex MF
When used with @option{-M} or @option{-MM}, specifies a
file to write the dependencies to. If no @option{-MF} switch is given
the preprocessor sends the rules to the same place it would send
preprocessed output.
When used with the driver options @option{-MD} or @option{-MMD},
@option{-MF} overrides the default dependency output file.
If @var{file} is @file{-}, then the dependencies are written to @file{stdout}.
@item -MG
@opindex MG
In conjunction with an option such as @option{-M} requesting
dependency generation, @option{-MG} assumes missing header files are
generated files and adds them to the dependency list without raising
an error. The dependency filename is taken directly from the
@code{#include} directive without prepending any path. @option{-MG}
also suppresses preprocessed output, as a missing header file renders
this useless.
This feature is used in automatic updating of makefiles.
@item -Mno-modules
@opindex Mno-modules
Disable dependency generation for compiled module interfaces.
@item -MP
@opindex MP
This option instructs CPP to add a phony target for each dependency
other than the main file, causing each to depend on nothing. These
dummy rules work around errors @command{make} gives if you remove header
files without updating the @file{Makefile} to match.
This is typical output:
@smallexample
test.o: test.c test.h
test.h:
@end smallexample
@item -MT @var{target}
@opindex MT
Change the target of the rule emitted by dependency generation. By
default CPP takes the name of the main input file, deletes any
directory components and any file suffix such as @samp{.c}, and
appends the platform's usual object suffix. The result is the target.
An @option{-MT} option sets the target to be exactly the string you
specify. If you want multiple targets, you can specify them as a single
argument to @option{-MT}, or use multiple @option{-MT} options.
For example, @option{@w{-MT '$(objpfx)foo.o'}} might give
@smallexample
$(objpfx)foo.o: foo.c
@end smallexample
@item -MQ @var{target}
@opindex MQ
Same as @option{-MT}, but it quotes any characters which are special to
Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives
@smallexample
$$(objpfx)foo.o: foo.c
@end smallexample
The default target is automatically quoted, as if it were given with
@option{-MQ}.
@item -MD
@opindex MD
@option{-MD} is equivalent to @option{-M -MF @var{file}}, except that
@option{-E} is not implied. The driver determines @var{file} based on
whether an @option{-o} option is given. If it is, the driver uses its
argument but with a suffix of @file{.d}, otherwise it takes the name
of the input file, removes any directory components and suffix, and
applies a @file{.d} suffix.
If @option{-MD} is used in conjunction with @option{-E}, any
@option{-o} switch is understood to specify the dependency output file
(@pxref{dashMF,,-MF}), but if used without @option{-E}, each @option{-o}
is understood to specify a target object file.
Since @option{-E} is not implied, @option{-MD} can be used to generate
a dependency output file as a side effect of the compilation process.
@item -MMD
@opindex MMD
Like @option{-MD} except mention only user header files, not system
header files.
@item -fpreprocessed
@opindex fpreprocessed
Indicate to the preprocessor that the input file has already been
preprocessed. This suppresses things like macro expansion, trigraph
conversion, escaped newline splicing, and processing of most directives.
The preprocessor still recognizes and removes comments, so that you can
pass a file preprocessed with @option{-C} to the compiler without
problems. In this mode the integrated preprocessor is little more than
a tokenizer for the front ends.
@option{-fpreprocessed} is implicit if the input file has one of the
extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the
extensions that GCC uses for preprocessed files created by
@option{-save-temps}.
@item -fdirectives-only
@opindex fdirectives-only
When preprocessing, handle directives, but do not expand macros.
The option's behavior depends on the @option{-E} and @option{-fpreprocessed}
options.
With @option{-E}, preprocessing is limited to the handling of directives
such as @code{#define}, @code{#ifdef}, and @code{#error}. Other
preprocessor operations, such as macro expansion and trigraph
conversion are not performed. In addition, the @option{-dD} option is
implicitly enabled.
With @option{-fpreprocessed}, predefinition of command line and most
builtin macros is disabled. Macros such as @code{__LINE__}, which are
contextually dependent, are handled normally. This enables compilation of
files previously preprocessed with @code{-E -fdirectives-only}.
With both @option{-E} and @option{-fpreprocessed}, the rules for
@option{-fpreprocessed} take precedence. This enables full preprocessing of
files previously preprocessed with @code{-E -fdirectives-only}.
@item -fdollars-in-identifiers
@opindex fdollars-in-identifiers
@anchor{fdollars-in-identifiers}
Accept @samp{$} in identifiers.
@ifset cppmanual
@xref{Identifier characters}.
@end ifset
@item -fextended-identifiers
@opindex fextended-identifiers
Accept universal character names and extended characters in
identifiers. This option is enabled by default for C99 (and later C
standard versions) and C++.
@item -fno-canonical-system-headers
@opindex fno-canonical-system-headers
When preprocessing, do not shorten system header paths with canonicalization.
@item -fmax-include-depth=@var{depth}
@opindex fmax-include-depth
Set the maximum depth of the nested #include. The default is 200.
@item -ftabstop=@var{width}
@opindex ftabstop
Set the distance between tab stops. This helps the preprocessor report
correct column numbers in warnings or errors, even if tabs appear on the
line. If the value is less than 1 or greater than 100, the option is
ignored. The default is 8.
@item -ftrack-macro-expansion@r{[}=@var{level}@r{]}
@opindex ftrack-macro-expansion
Track locations of tokens across macro expansions. This allows the
compiler to emit diagnostic about the current macro expansion stack
when a compilation error occurs in a macro expansion. Using this
option makes the preprocessor and the compiler consume more
memory. The @var{level} parameter can be used to choose the level of
precision of token location tracking thus decreasing the memory
consumption if necessary. Value @samp{0} of @var{level} de-activates
this option. Value @samp{1} tracks tokens locations in a
degraded mode for the sake of minimal memory overhead. In this mode
all tokens resulting from the expansion of an argument of a
function-like macro have the same location. Value @samp{2} tracks
tokens locations completely. This value is the most memory hungry.
When this option is given no argument, the default parameter value is
@samp{2}.
Note that @code{-ftrack-macro-expansion=2} is activated by default.
@item -fmacro-prefix-map=@var{old}=@var{new}
@opindex fmacro-prefix-map
When preprocessing files residing in directory @file{@var{old}},
expand the @code{__FILE__} and @code{__BASE_FILE__} macros as if the
files resided in directory @file{@var{new}} instead. This can be used
to change an absolute path to a relative path by using @file{.} for
@var{new} which can result in more reproducible builds that are
location independent. This option also affects
@code{__builtin_FILE()} during compilation. See also
@option{-ffile-prefix-map}.
@item -fexec-charset=@var{charset}
@opindex fexec-charset
@cindex character set, execution
Set the execution character set, used for string and character
constants. The default is UTF-8. @var{charset} can be any encoding
supported by the system's @code{iconv} library routine.
@item -fwide-exec-charset=@var{charset}
@opindex fwide-exec-charset
@cindex character set, wide execution
Set the wide execution character set, used for wide string and
character constants. The default is one of UTF-32BE, UTF-32LE, UTF-16BE,
or UTF-16LE, whichever corresponds to the width of @code{wchar_t} and the
big-endian or little-endian byte order being used for code generation. As
with @option{-fexec-charset}, @var{charset} can be any encoding supported
by the system's @code{iconv} library routine; however, you will have
problems with encodings that do not fit exactly in @code{wchar_t}.
@item -finput-charset=@var{charset}
@opindex finput-charset
@cindex character set, input
Set the input character set, used for translation from the character
set of the input file to the source character set used by GCC@. If the
locale does not specify, or GCC cannot get this information from the
locale, the default is UTF-8. This can be overridden by either the locale
or this command-line option. Currently the command-line option takes
precedence if there's a conflict. @var{charset} can be any encoding
supported by the system's @code{iconv} library routine.
@ifclear cppmanual
@item -fpch-deps
@opindex fpch-deps
When using precompiled headers (@pxref{Precompiled Headers}), this flag
causes the dependency-output flags to also list the files from the
precompiled header's dependencies. If not specified, only the
precompiled header are listed and not the files that were used to
create it, because those files are not consulted when a precompiled
header is used.
@item -fpch-preprocess
@opindex fpch-preprocess
This option allows use of a precompiled header (@pxref{Precompiled
Headers}) together with @option{-E}. It inserts a special @code{#pragma},
@code{#pragma GCC pch_preprocess "@var{filename}"} in the output to mark
the place where the precompiled header was found, and its @var{filename}.
When @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma}
and loads the PCH@.
This option is off by default, because the resulting preprocessed output
is only really suitable as input to GCC@. It is switched on by
@option{-save-temps}.
You should not write this @code{#pragma} in your own code, but it is
safe to edit the filename if the PCH file is available in a different
location. The filename may be absolute or it may be relative to GCC's
current directory.
@end ifclear
@item -fworking-directory
@opindex fworking-directory
@opindex fno-working-directory
Enable generation of linemarkers in the preprocessor output that
let the compiler know the current working directory at the time of
preprocessing. When this option is enabled, the preprocessor
emits, after the initial linemarker, a second linemarker with the
current working directory followed by two slashes. GCC uses this
directory, when it's present in the preprocessed input, as the
directory emitted as the current working directory in some debugging
information formats. This option is implicitly enabled if debugging
information is enabled, but this can be inhibited with the negated
form @option{-fno-working-directory}. If the @option{-P} flag is
present in the command line, this option has no effect, since no
@code{#line} directives are emitted whatsoever.
@item -A @var{predicate}=@var{answer}
@opindex A
Make an assertion with the predicate @var{predicate} and answer
@var{answer}. This form is preferred to the older form @option{-A
@var{predicate}(@var{answer})}, which is still supported, because
it does not use shell special characters.
@ifset cppmanual
@xref{Obsolete Features}.
@end ifset
@item -A -@var{predicate}=@var{answer}
Cancel an assertion with the predicate @var{predicate} and answer
@var{answer}.
@item -C
@opindex C
Do not discard comments. All comments are passed through to the output
file, except for comments in processed directives, which are deleted
along with the directive.
You should be prepared for side effects when using @option{-C}; it
causes the preprocessor to treat comments as tokens in their own right.
For example, comments appearing at the start of what would be a
directive line have the effect of turning that line into an ordinary
source line, since the first token on the line is no longer a @samp{#}.
@item -CC
@opindex CC
Do not discard comments, including during macro expansion. This is
like @option{-C}, except that comments contained within macros are
also passed through to the output file where the macro is expanded.
In addition to the side effects of the @option{-C} option, the
@option{-CC} option causes all C++-style comments inside a macro
to be converted to C-style comments. This is to prevent later use
of that macro from inadvertently commenting out the remainder of
the source line.
The @option{-CC} option is generally used to support lint comments.
@item -P
@opindex P
Inhibit generation of linemarkers in the output from the preprocessor.
This might be useful when running the preprocessor on something that is
not C code, and will be sent to a program which might be confused by the
linemarkers.
@ifset cppmanual
@xref{Preprocessor Output}.
@end ifset
@cindex traditional C language
@cindex C language, traditional
@item -traditional
@itemx -traditional-cpp
@opindex traditional-cpp
@opindex traditional
Try to imitate the behavior of pre-standard C preprocessors, as
opposed to ISO C preprocessors.
@ifset cppmanual
@xref{Traditional Mode}.
@end ifset
@ifclear cppmanual
See the GNU CPP manual for details.
@end ifclear
Note that GCC does not otherwise attempt to emulate a pre-standard
C compiler, and these options are only supported with the @option{-E}
switch, or when invoking CPP explicitly.
@item -trigraphs
@opindex trigraphs
Support ISO C trigraphs.
These are three-character sequences, all starting with @samp{??}, that
are defined by ISO C to stand for single characters. For example,
@samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character
constant for a newline.
@ifset cppmanual
@xref{Initial processing}.
@end ifset
@ifclear cppmanual
The nine trigraphs and their replacements are
@smallexample
Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??-
Replacement: [ ] @{ @} # \ ^ | ~
@end smallexample
@end ifclear
By default, GCC ignores trigraphs, but in
standard-conforming modes it converts them. See the @option{-std} and
@option{-ansi} options.
@item -remap
@opindex remap
Enable special code to work around file systems which only permit very
short file names, such as MS-DOS@.
@item -H
@opindex H
Print the name of each header file used, in addition to other normal
activities. Each name is indented to show how deep in the
@samp{#include} stack it is. Precompiled header files are also
printed, even if they are found to be invalid; an invalid precompiled
header file is printed with @samp{...x} and a valid one with @samp{...!} .
@item -d@var{letters}
@opindex d
Says to make debugging dumps during compilation as specified by
@var{letters}. The flags documented here are those relevant to the
preprocessor. Other @var{letters} are interpreted
by the compiler proper, or reserved for future versions of GCC, and so
are silently ignored. If you specify @var{letters} whose behavior
conflicts, the result is undefined.
@ifclear cppmanual
@xref{Developer Options}, for more information.
@end ifclear
@table @gcctabopt
@item -dM
@opindex dM
Instead of the normal output, generate a list of @samp{#define}
directives for all the macros defined during the execution of the
preprocessor, including predefined macros. This gives you a way of
finding out what is predefined in your version of the preprocessor.
Assuming you have no file @file{foo.h}, the command
@smallexample
touch foo.h; cpp -dM foo.h
@end smallexample
@noindent
shows all the predefined macros.
@ifclear cppmanual
If you use @option{-dM} without the @option{-E} option, @option{-dM} is
interpreted as a synonym for @option{-fdump-rtl-mach}.
@xref{Developer Options, , ,gcc}.
@end ifclear
@item -dD
@opindex dD
Like @option{-dM} except in two respects: it does @emph{not} include the
predefined macros, and it outputs @emph{both} the @samp{#define}
directives and the result of preprocessing. Both kinds of output go to
the standard output file.
@item -dN
@opindex dN
Like @option{-dD}, but emit only the macro names, not their expansions.
@item -dI
@opindex dI
Output @samp{#include} directives in addition to the result of
preprocessing.
@item -dU
@opindex dU
Like @option{-dD} except that only macros that are expanded, or whose
definedness is tested in preprocessor directives, are output; the
output is delayed until the use or test of the macro; and
@samp{#undef} directives are also output for macros tested but
undefined at the time.
@end table
@item -fdebug-cpp
@opindex fdebug-cpp
This option is only useful for debugging GCC. When used from CPP or with
@option{-E}, it dumps debugging information about location maps. Every
token in the output is preceded by the dump of the map its location
belongs to.
When used from GCC without @option{-E}, this option has no effect.

82
gcc/doc/cppwarnopts.texi Normal file
View File

@ -0,0 +1,82 @@
@c Copyright (C) 1999-2022 Free Software Foundation, Inc.
@c This is part of the CPP and GCC manuals.
@c For copying conditions, see the file gcc.texi.
@c ---------------------------------------------------------------------
@c Options affecting preprocessor warnings
@c ---------------------------------------------------------------------
@c If this file is included with the flag ``cppmanual'' set, it is
@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
@item -Wcomment
@itemx -Wcomments
@opindex Wcomment
@opindex Wcomments
Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
comment, or whenever a backslash-newline appears in a @samp{//} comment.
This warning is enabled by @option{-Wall}.
@item -Wtrigraphs
@opindex Wtrigraphs
@anchor{Wtrigraphs}
Warn if any trigraphs are encountered that might change the meaning of
the program. Trigraphs within comments are not warned about,
except those that would form escaped newlines.
This option is implied by @option{-Wall}. If @option{-Wall} is not
given, this option is still enabled unless trigraphs are enabled. To
get trigraph conversion without warnings, but get the other
@option{-Wall} warnings, use @samp{-trigraphs -Wall -Wno-trigraphs}.
@item -Wundef
@opindex Wundef
@opindex Wno-undef
Warn if an undefined identifier is evaluated in an @code{#if} directive.
Such identifiers are replaced with zero.
@item -Wexpansion-to-defined
@opindex Wexpansion-to-defined
Warn whenever @samp{defined} is encountered in the expansion of a macro
(including the case where the macro is expanded by an @samp{#if} directive).
Such usage is not portable.
This warning is also enabled by @option{-Wpedantic} and @option{-Wextra}.
@item -Wunused-macros
@opindex Wunused-macros
Warn about macros defined in the main file that are unused. A macro
is @dfn{used} if it is expanded or tested for existence at least once.
The preprocessor also warns if the macro has not been used at the
time it is redefined or undefined.
Built-in macros, macros defined on the command line, and macros
defined in include files are not warned about.
@emph{Note:} If a macro is actually used, but only used in skipped
conditional blocks, then the preprocessor reports it as unused. To avoid the
warning in such a case, you might improve the scope of the macro's
definition by, for example, moving it into the first skipped block.
Alternatively, you could provide a dummy use with something like:
@smallexample
#if defined the_macro_causing_the_warning
#endif
@end smallexample
@item -Wno-endif-labels
@opindex Wno-endif-labels
@opindex Wendif-labels
Do not warn whenever an @code{#else} or an @code{#endif} are followed by text.
This sometimes happens in older programs with code of the form
@smallexample
#if FOO
@dots{}
#else FOO
@dots{}
#endif FOO
@end smallexample
@noindent
The second and third @code{FOO} should be in comments.
This warning is on by default.

25550
gcc/doc/extend.texi Normal file
View File

File diff suppressed because it is too large Load Diff

273
gcc/doc/fragments.texi Normal file
View File

@ -0,0 +1,273 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Fragments
@chapter Makefile Fragments
@cindex makefile fragment
When you configure GCC using the @file{configure} script, it will
construct the file @file{Makefile} from the template file
@file{Makefile.in}. When it does this, it can incorporate makefile
fragments from the @file{config} directory. These are used to set
Makefile parameters that are not amenable to being calculated by
autoconf. The list of fragments to incorporate is set by
@file{config.gcc} (and occasionally @file{config.build}
and @file{config.host}); @xref{System Config}.
Fragments are named either @file{t-@var{target}} or @file{x-@var{host}},
depending on whether they are relevant to configuring GCC to produce
code for a particular target, or to configuring GCC to run on a
particular host. Here @var{target} and @var{host} are mnemonics
which usually have some relationship to the canonical system name, but
no formal connection.
If these files do not exist, it means nothing needs to be added for a
given target or host. Most targets need a few @file{t-@var{target}}
fragments, but needing @file{x-@var{host}} fragments is rare.
@menu
* Target Fragment:: Writing @file{t-@var{target}} files.
* Host Fragment:: Writing @file{x-@var{host}} files.
@end menu
@node Target Fragment
@section Target Makefile Fragments
@cindex target makefile fragment
@cindex @file{t-@var{target}}
Target makefile fragments can set these Makefile variables.
@table @code
@findex LIBGCC2_CFLAGS
@item LIBGCC2_CFLAGS
Compiler flags to use when compiling @file{libgcc2.c}.
@findex LIB2FUNCS_EXTRA
@item LIB2FUNCS_EXTRA
A list of source file names to be compiled or assembled and inserted
into @file{libgcc.a}.
@findex CRTSTUFF_T_CFLAGS
@item CRTSTUFF_T_CFLAGS
Special flags used when compiling @file{crtstuff.c}.
@xref{Initialization}.
@findex CRTSTUFF_T_CFLAGS_S
@item CRTSTUFF_T_CFLAGS_S
Special flags used when compiling @file{crtstuff.c} for shared
linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
in @code{EXTRA-PARTS}.
@xref{Initialization}.
@findex MULTILIB_OPTIONS
@item MULTILIB_OPTIONS
For some targets, invoking GCC in different ways produces objects
that cannot be linked together. For example, for some targets GCC
produces both big and little endian code. For these targets, you must
arrange for multiple versions of @file{libgcc.a} to be compiled, one for
each set of incompatible options. When GCC invokes the linker, it
arranges to link in the right version of @file{libgcc.a}, based on
the command line options used.
The @code{MULTILIB_OPTIONS} macro lists the set of options for which
special versions of @file{libgcc.a} must be built. Write options that
are mutually incompatible side by side, separated by a slash. Write
options that may be used together separated by a space. The build
procedure will build all combinations of compatible options.
For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
msoft-float}, @file{Makefile} will build special versions of
@file{libgcc.a} using the following sets of options: @option{-m68000},
@option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
@samp{-m68020 -msoft-float}.
@findex MULTILIB_DIRNAMES
@item MULTILIB_DIRNAMES
If @code{MULTILIB_OPTIONS} is used, this variable specifies the
directory names that should be used to hold the various libraries.
Write one element in @code{MULTILIB_DIRNAMES} for each element in
@code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
as spaces.
@code{MULTILIB_DIRNAMES} describes the multilib directories using GCC
conventions and is applied to directories that are part of the GCC
installation. When multilib-enabled, the compiler will add a
subdirectory of the form @var{prefix}/@var{multilib} before each
directory in the search path for libraries and crt files.
For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
@samp{m68000 m68020 msoft-float}. You may specify a different value if
you desire a different set of directory names.
@findex MULTILIB_MATCHES
@item MULTILIB_MATCHES
Sometimes the same option may be written in two different ways. If an
option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
items of the form @samp{option=option} to describe all relevant
synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
@findex MULTILIB_EXCEPTIONS
@item MULTILIB_EXCEPTIONS
Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
specified, there are combinations that should not be built. In that
case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
in shell case syntax that should not be built.
For example the ARM processor cannot execute both hardware floating
point instructions and the reduced size THUMB instructions at the same
time, so there is no need to build libraries with both of these
options enabled. Therefore @code{MULTILIB_EXCEPTIONS} is set to:
@smallexample
*mthumb/*mhard-float*
@end smallexample
@findex MULTILIB_REQUIRED
@item MULTILIB_REQUIRED
Sometimes when there are only a few combinations are required, it would
be a big effort to come up with a @code{MULTILIB_EXCEPTIONS} list to
cover all undesired ones. In such a case, just listing all the required
combinations in @code{MULTILIB_REQUIRED} would be more straightforward.
The way to specify the entries in @code{MULTILIB_REQUIRED} is same with
the way used for @code{MULTILIB_EXCEPTIONS}, only this time what are
required will be specified. Suppose there are multiple sets of
@code{MULTILIB_OPTIONS} and only two combinations are required, one
for ARMv7-M and one for ARMv7-R with hard floating-point ABI and FPU, the
@code{MULTILIB_REQUIRED} can be set to:
@smallexample
@code{MULTILIB_REQUIRED} = mthumb/march=armv7-m
@code{MULTILIB_REQUIRED} += march=armv7-r/mfloat-abi=hard/mfpu=vfpv3-d16
@end smallexample
The @code{MULTILIB_REQUIRED} can be used together with
@code{MULTILIB_EXCEPTIONS}. The option combinations generated from
@code{MULTILIB_OPTIONS} will be filtered by @code{MULTILIB_EXCEPTIONS}
and then by @code{MULTILIB_REQUIRED}.
@findex MULTILIB_REUSE
@item MULTILIB_REUSE
Sometimes it is desirable to reuse one existing multilib for different
sets of options. Such kind of reuse can minimize the number of multilib
variants. And for some targets it is better to reuse an existing multilib
than to fall back to default multilib when there is no corresponding multilib.
This can be done by adding reuse rules to @code{MULTILIB_REUSE}.
A reuse rule is comprised of two parts connected by equality sign. The left
part is the option set used to build multilib and the right part is the option
set that will reuse this multilib. Both parts should only use options
specified in @code{MULTILIB_OPTIONS} and the equality signs found in options
name should be replaced with periods. An explicit period in the rule can be
escaped by preceding it with a backslash. The order of options in the left
part matters and should be same with those specified in
@code{MULTILIB_REQUIRED} or aligned with the order in @code{MULTILIB_OPTIONS}.
There is no such limitation for options in the right part as we don't build
multilib from them.
@code{MULTILIB_REUSE} is different from @code{MULTILIB_MATCHES} in that it
sets up relations between two option sets rather than two options. Here is an
example to demo how we reuse libraries built in Thumb mode for applications built
in ARM mode:
@smallexample
@code{MULTILIB_REUSE} = mthumb/march.armv7-r=marm/march.armv7-r
@end smallexample
Before the advent of @code{MULTILIB_REUSE}, GCC select multilib by comparing command
line options with options used to build multilib. The @code{MULTILIB_REUSE} is
complementary to that way. Only when the original comparison matches nothing it will
work to see if it is OK to reuse some existing multilib.
@findex MULTILIB_EXTRA_OPTS
@item MULTILIB_EXTRA_OPTS
Sometimes it is desirable that when building multiple versions of
@file{libgcc.a} certain options should always be passed on to the
compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
of options to be used for all builds. If you set this, you should
probably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it.
@findex MULTILIB_OSDIRNAMES
@item MULTILIB_OSDIRNAMES
If @code{MULTILIB_OPTIONS} is used, this variable specifies
a list of subdirectory names, that are used to modify the search
path depending on the chosen multilib. Unlike @code{MULTILIB_DIRNAMES},
@code{MULTILIB_OSDIRNAMES} describes the multilib directories using
operating systems conventions, and is applied to the directories such as
@code{lib} or those in the @env{LIBRARY_PATH} environment variable.
The format is either the same as of
@code{MULTILIB_DIRNAMES}, or a set of mappings. When it is the same
as @code{MULTILIB_DIRNAMES}, it describes the multilib directories
using operating system conventions, rather than GCC conventions. When it is a set
of mappings of the form @var{gccdir}=@var{osdir}, the left side gives
the GCC convention and the right gives the equivalent OS defined
location. If the @var{osdir} part begins with a @samp{!},
GCC will not search in the non-multilib directory and use
exclusively the multilib directory. Otherwise, the compiler will
examine the search path for libraries and crt files twice; the first
time it will add @var{multilib} to each directory in the search path,
the second it will not.
For configurations that support both multilib and multiarch,
@code{MULTILIB_OSDIRNAMES} also encodes the multiarch name, thus
subsuming @code{MULTIARCH_DIRNAME}. The multiarch name is appended to
each directory name, separated by a colon (e.g.@:
@samp{../lib32:i386-linux-gnu}).
Each multiarch subdirectory will be searched before the corresponding OS
multilib directory, for example @samp{/lib/i386-linux-gnu} before
@samp{/lib/../lib32}. The multiarch name will also be used to modify the
system header search path, as explained for @code{MULTIARCH_DIRNAME}.
@findex MULTIARCH_DIRNAME
@item MULTIARCH_DIRNAME
This variable specifies the multiarch name for configurations that are
multiarch-enabled but not multilibbed configurations.
The multiarch name is used to augment the search path for libraries, crt
files and system header files with additional locations. The compiler
will add a multiarch subdirectory of the form
@var{prefix}/@var{multiarch} before each directory in the library and
crt search path. It will also add two directories
@code{LOCAL_INCLUDE_DIR}/@var{multiarch} and
@code{NATIVE_SYSTEM_HEADER_DIR}/@var{multiarch}) to the system header
search path, respectively before @code{LOCAL_INCLUDE_DIR} and
@code{NATIVE_SYSTEM_HEADER_DIR}.
@code{MULTIARCH_DIRNAME} is not used for configurations that support
both multilib and multiarch. In that case, multiarch names are encoded
in @code{MULTILIB_OSDIRNAMES} instead.
More documentation about multiarch can be found at
@uref{https://wiki.debian.org/Multiarch}.
@findex SPECS
@item SPECS
Unfortunately, setting @code{MULTILIB_EXTRA_OPTS} is not enough, since
it does not affect the build of target libraries, at least not the
build of the default multilib. One possible work-around is to use
@code{DRIVER_SELF_SPECS} to bring options from the @file{specs} file
as if they had been passed in the compiler driver command line.
However, you don't want to be adding these options after the toolchain
is installed, so you can instead tweak the @file{specs} file that will
be used during the toolchain build, while you still install the
original, built-in @file{specs}. The trick is to set @code{SPECS} to
some other filename (say @file{specs.install}), that will then be
created out of the built-in specs, and introduce a @file{Makefile}
rule to generate the @file{specs} file that's going to be used at
build time out of your @file{specs.install}.
@item T_CFLAGS
These are extra flags to pass to the C compiler. They are used both
when building GCC, and when compiling things with the just-built GCC@.
This variable is deprecated and should not be used.
@end table
@node Host Fragment
@section Host Makefile Fragments
@cindex host makefile fragment
@cindex @file{x-@var{host}}
The use of @file{x-@var{host}} fragments is discouraged. You should only
use it for makefile dependencies.

61
gcc/doc/frontends.texi Normal file
View File

@ -0,0 +1,61 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node G++ and GCC
@chapter Programming Languages Supported by GCC
@cindex GCC
@cindex GNU Compiler Collection
@cindex GNU C Compiler
@cindex Ada
@cindex D
@cindex Fortran
@cindex Go
@cindex Objective-C
@cindex Objective-C++
GCC stands for ``GNU Compiler Collection''. GCC is an integrated
distribution of compilers for several major programming languages. These
languages currently include C, C++, Objective-C, Objective-C++,
Fortran, Ada, D, and Go.
The abbreviation @dfn{GCC} has multiple meanings in common use. The
current official meaning is ``GNU Compiler Collection'', which refers
generically to the complete suite of tools. The name historically stood
for ``GNU C Compiler'', and this usage is still common when the emphasis
is on compiling C programs. Finally, the name is also used when speaking
of the @dfn{language-independent} component of GCC: code shared among the
compilers for all supported languages.
The language-independent component of GCC includes the majority of the
optimizers, as well as the ``back ends'' that generate machine code for
various processors.
@cindex COBOL
@cindex Mercury
The part of a compiler that is specific to a particular language is
called the ``front end''. In addition to the front ends that are
integrated components of GCC, there are several other front ends that
are maintained separately. These support languages such as
Mercury, and COBOL@. To use these, they must be built together with
GCC proper.
@cindex C++
@cindex G++
@cindex Ada
@cindex GNAT
Most of the compilers for languages other than C have their own names.
The C++ compiler is G++, the Ada compiler is GNAT, and so on. When we
talk about compiling one of those languages, we might refer to that
compiler by its own name, or as GCC@. Either is correct.
@cindex compiler compared to C++ preprocessor
@cindex intermediate C version, nonexistent
@cindex C intermediate output, nonexistent
Historically, compilers for many languages, including C++ and Fortran,
have been implemented as ``preprocessors'' which emit another high
level language such as C@. None of the compilers included in GCC are
implemented this way; they all generate machine code directly. This
sort of preprocessor should not be confused with the @dfn{C
preprocessor}, which is an integral feature of the C, C++, Objective-C
and Objective-C++ languages.

219
gcc/doc/gcc.texi Normal file
View File

@ -0,0 +1,219 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename gcc.info
@c INTERNALS is used by md.texi to determine whether to include the
@c whole of that file, in the internals manual, or only the part
@c dealing with constraints, in the user manual.
@clear INTERNALS
@c NOTE: checks/things to do:
@c
@c -have bob do a search in all seven files for "mew" (ideally --mew,
@c but i may have forgotten the occasional "--"..).
@c Just checked... all have `--'! Bob 22Jul96
@c Use this to search: grep -n '\-\-mew' *.texi
@c -item/itemx, text after all (sub/sub)section titles, etc..
@c -consider putting the lists of options on pp 17--> etc in columns or
@c some such.
@c -overfulls. do a search for "mew" in the files, and you will see
@c overfulls that i noted but could not deal with.
@c -have to add text: beginning of chapter 8
@c
@c anything else? --mew 10feb93
@include gcc-common.texi
@settitle Using the GNU Compiler Collection (GCC)
@c Create a separate index for command line options.
@defcodeindex op
@c Merge the standard indexes into a single one.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@paragraphindent 1
@c %**end of header
@copying
Copyright @copyright{} 1988-2022 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.
@end copying
@ifnottex
@dircategory Software development
@direntry
* gcc: (gcc). The GNU Compiler Collection.
* g++: (gcc). The GNU C++ compiler.
* gcov: (gcc) Gcov. @command{gcov}---a test coverage program.
* gcov-tool: (gcc) Gcov-tool. @command{gcov-tool}---an offline gcda profile processing program.
* gcov-dump: (gcc) Gcov-dump. @command{gcov-dump}---an offline gcda and gcno profile dump tool.
* lto-dump: (gcc) lto-dump. @command{lto-dump}---Tool for
dumping LTO object files.
@end direntry
This file documents the use of the GNU compilers.
@sp 1
@insertcopying
@sp 1
@end ifnottex
@setchapternewpage odd
@titlepage
@title Using the GNU Compiler Collection
@versionsubtitle
@author Richard M. Stallman and the @sc{GCC} Developer Community
@page
@vskip 0pt plus 1filll
Published by:
@multitable @columnfractions 0.5 0.5
@item GNU Press
@tab Website: @uref{http://www.gnupress.org}
@item a division of the
@tab General: @email{press@@gnu.org}
@item Free Software Foundation
@tab Orders: @email{sales@@gnu.org}
@item 51 Franklin Street, Fifth Floor
@tab Tel 617-542-5942
@item Boston, MA 02110-1301 USA
@tab Fax 617-542-2652
@end multitable
@sp 2
@ifset FSFPRINT
@c Update this ISBN when printing a new edition.
@acronym{ISBN} 1-882114-39-6
Cover art by Gary M. Torrisi. Cover design by Jonathan Richard.
@end ifset
@ifclear FSFPRINT
Last printed October 2003 for GCC 3.3.1.@*
Printed copies are available for $45 each.
@end ifclear
@sp 1
@insertcopying
@end titlepage
@summarycontents
@contents
@page
@node Top, G++ and GCC
@top Introduction
@cindex introduction
This manual documents how to use the GNU compilers,
as well as their features and incompatibilities, and how to report
bugs. It corresponds to the compilers
@ifset VERSION_PACKAGE
@value{VERSION_PACKAGE}
@end ifset
version @value{version-GCC}.
The internals of the GNU compilers, including how to port them to new
targets and some information about how to write front ends for new
languages, are documented in a separate manual. @xref{Top,,
Introduction, gccint, GNU Compiler Collection (GCC) Internals}.
@menu
* G++ and GCC:: You can compile C or C++ programs.
* Standards:: Language standards supported by GCC.
* Invoking GCC:: Command options supported by @samp{gcc}.
* C Implementation:: How GCC implements the ISO C specification.
* C++ Implementation:: How GCC implements the ISO C++ specification.
* C Extensions:: GNU extensions to the C language family.
* C++ Extensions:: GNU extensions to the C++ language.
* Objective-C:: GNU Objective-C runtime features.
* Compatibility:: Binary Compatibility
* Gcov:: @command{gcov}---a test coverage program.
* Gcov-tool:: @command{gcov-tool}---an offline gcda profile processing program.
* Gcov-dump:: @command{gcov-dump}---an offline gcda and gcno profile dump tool.
* lto-dump:: @command{lto-dump}---Tool for dumping LTO
object files.
* Trouble:: If you have trouble using GCC.
* Bugs:: How, why and where to report bugs.
* Service:: How To Get Help with GCC
* Contributing:: How to contribute to testing and developing GCC.
* Funding:: How to help assure funding for free software.
* GNU Project:: The GNU Project and GNU/Linux.
* Copying:: GNU General Public License says
how you can copy and share GCC.
* GNU Free Documentation License:: How you can copy and share this manual.
* Contributors:: People who have contributed to GCC.
* Option Index:: Index to command line options.
* Keyword Index:: Index of concepts and symbol names.
@end menu
@include frontends.texi
@include standards.texi
@include invoke.texi
@include implement-c.texi
@include implement-cxx.texi
@include extend.texi
@include objc.texi
@include compat.texi
@include gcov.texi
@include gcov-tool.texi
@include gcov-dump.texi
@include lto-dump.texi
@include trouble.texi
@include bugreport.texi
@include service.texi
@include contribute.texi
@include funding.texi
@include gnu.texi
@include gpl_v3.texi
@c ---------------------------------------------------------------------
@c GFDL
@c ---------------------------------------------------------------------
@include fdl.texi
@include contrib.texi
@c ---------------------------------------------------------------------
@c Indexes
@c ---------------------------------------------------------------------
@node Option Index
@unnumbered Option Index
GCC's command line options are indexed here without any initial @samp{-}
or @samp{--}. Where an option has both positive and negative forms
(such as @option{-f@var{option}} and @option{-fno-@var{option}}),
relevant entries in the manual are indexed under the most appropriate
form; it may sometimes be useful to look up both forms.
@printindex op
@node Keyword Index
@unnumbered Keyword Index
@printindex cp
@c ---------------------------------------------------------------------
@c Epilogue
@c ---------------------------------------------------------------------
@bye

206
gcc/doc/gccint.texi Normal file
View File

@ -0,0 +1,206 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename gccint.info
@c INTERNALS is used by md.texi to determine whether to include the
@c whole of that file, in the internals manual, or only the part
@c dealing with constraints, in the user manual.
@set INTERNALS
@c See miscellaneous notes in gcc.texi on checks/things to do.
@include gcc-common.texi
@settitle GNU Compiler Collection (GCC) Internals
@c Create a separate index for command line options.
@defcodeindex op
@c Merge the standard indexes into a single one.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@paragraphindent 1
@c %**end of header
@copying
Copyright @copyright{} 1988-2022 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.
@end copying
@ifnottex
@dircategory Software development
@direntry
* gccint: (gccint). Internals of the GNU Compiler Collection.
@end direntry
This file documents the internals of the GNU compilers.
@sp 1
@insertcopying
@sp 1
@end ifnottex
@setchapternewpage odd
@titlepage
@title GNU Compiler Collection Internals
@versionsubtitle
@author Richard M. Stallman and the @sc{GCC} Developer Community
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@summarycontents
@contents
@page
@node Top, Contributing
@top Introduction
@cindex introduction
This manual documents the internals of the GNU compilers, including
how to port them to new targets and some information about how to
write front ends for new languages. It corresponds to the compilers
@ifset VERSION_PACKAGE
@value{VERSION_PACKAGE}
@end ifset
version @value{version-GCC}. The use of the GNU compilers is documented in a
separate manual. @xref{Top,, Introduction, gcc, Using the GNU
Compiler Collection (GCC)}.
This manual is mainly a reference manual rather than a tutorial. It
discusses how to contribute to GCC (@pxref{Contributing}), the
characteristics of the machines supported by GCC as hosts and targets
(@pxref{Portability}), how GCC relates to the ABIs on such systems
(@pxref{Interface}), and the characteristics of the languages for
which GCC front ends are written (@pxref{Languages}). It then
describes the GCC source tree structure and build system, some of the
interfaces to GCC front ends, and how support for a target system is
implemented in GCC@.
Additional tutorial information is linked to from
@uref{https://gcc.gnu.org/readings.html}.
@menu
* Contributing:: How to contribute to testing and developing GCC.
* Portability:: Goals of GCC's portability features.
* Interface:: Function-call interface of GCC output.
* Libgcc:: Low-level runtime library used by GCC.
* Languages:: Languages for which GCC front ends are written.
* Source Tree:: GCC source tree structure and build system.
* Testsuites:: GCC testsuites.
* Options:: Option specification files.
* Passes:: Order of passes, what they do, and what each file is for.
* poly_int:: Representation of runtime sizes and offsets.
* GENERIC:: Language-independent representation generated by Front Ends
* GIMPLE:: Tuple representation used by Tree SSA optimizers
* Tree SSA:: Analysis and optimization of GIMPLE
* RTL:: Machine-dependent low-level intermediate representation.
* Control Flow:: Maintaining and manipulating the control flow graph.
* Loop Analysis and Representation:: Analysis and representation of loops
* Machine Desc:: How to write machine description instruction patterns.
* Target Macros:: How to write the machine description C macros and functions.
* Host Config:: Writing the @file{xm-@var{machine}.h} file.
* Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
* Collect2:: How @code{collect2} works; how it finds @code{ld}.
* Header Dirs:: Understanding the standard header file directories.
* Type Information:: GCC's memory management; generating type information.
* Plugins:: Extending the compiler with plugins.
* LTO:: Using Link-Time Optimization.
* Match and Simplify:: How to write expression simplification patterns for GIMPLE and GENERIC
* Static Analyzer:: Working with the static analyzer.
* User Experience Guidelines:: Guidelines for implementing diagnostics and options.
* Funding:: How to help assure funding for free software.
* GNU Project:: The GNU Project and GNU/Linux.
* Copying:: GNU General Public License says
how you can copy and share GCC.
* GNU Free Documentation License:: How you can copy and share this manual.
* Contributors:: People who have contributed to GCC.
* Option Index:: Index to command line options.
* Concept Index:: Index of concepts and symbol names.
@end menu
@include contribute.texi
@include portability.texi
@include interface.texi
@include libgcc.texi
@include languages.texi
@include sourcebuild.texi
@include options.texi
@include passes.texi
@include poly-int.texi
@include generic.texi
@include gimple.texi
@include tree-ssa.texi
@include rtl.texi
@include cfg.texi
@include loop.texi
@include md.texi
@include tm.texi
@include hostconfig.texi
@include fragments.texi
@include collect2.texi
@include headerdirs.texi
@include gty.texi
@include plugins.texi
@include lto.texi
@include match-and-simplify.texi
@include analyzer.texi
@include ux.texi
@include funding.texi
@include gnu.texi
@include gpl_v3.texi
@c ---------------------------------------------------------------------
@c GFDL
@c ---------------------------------------------------------------------
@include fdl.texi
@include contrib.texi
@c ---------------------------------------------------------------------
@c Indexes
@c ---------------------------------------------------------------------
@node Option Index
@unnumbered Option Index
GCC's command line options are indexed here without any initial @samp{-}
or @samp{--}. Where an option has both positive and negative forms
(such as @option{-f@var{option}} and @option{-fno-@var{option}}),
relevant entries in the manual are indexed under the most appropriate
form; it may sometimes be useful to look up both forms.
@printindex op
@node Concept Index
@unnumbered Concept Index
@printindex cp
@c ---------------------------------------------------------------------
@c Epilogue
@c ---------------------------------------------------------------------
@bye

99
gcc/doc/gcov-dump.texi Normal file
View File

@ -0,0 +1,99 @@
@c Copyright (C) 2017-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@ignore
@c man begin COPYRIGHT
Copyright @copyright{} 2017-2022 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 ``GNU General Public License'' and ``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 gfdl(7) man page.
(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.
@c man end
@c Set file name and title for the man page.
@setfilename gcov-dump
@settitle offline gcda and gcno profile dump tool
@end ignore
@node Gcov-dump
@chapter @command{gcov-dump}---an Offline Gcda and Gcno Profile Dump Tool
@menu
* Gcov-dump Intro:: Introduction to gcov-dump.
* Invoking Gcov-dump:: How to use gcov-dump.
@end menu
@node Gcov-dump Intro
@section Introduction to @command{gcov-dump}
@c man begin DESCRIPTION
@command{gcov-dump} is a tool you can use in conjunction with GCC to
dump content of gcda and gcno profile files offline.
@c man end
@node Invoking Gcov-dump
@section Invoking @command{gcov-dump}
@smallexample
Usage: gcov-dump @r{[}@var{OPTION}@r{]} ... @var{gcovfiles}
@end smallexample
@command{gcov-dump} accepts the following options:
@ignore
@c man begin SYNOPSIS
gcov-dump [@option{-v}|@option{--version}]
[@option{-h}|@option{--help}]
[@option{-l}|@option{--long}]
[@option{-p}|@option{--positions}]
[@option{-r}|@option{--raw}]
[@option{-s}|@option{--stable}]
@var{gcovfiles}
@c man end
@end ignore
@c man begin OPTIONS
@table @gcctabopt
@item -h
@itemx --help
Display help about using @command{gcov-dump} (on the standard output), and
exit without doing any further processing.
@item -l
@itemx --long
Dump content of records.
@item -p
@itemx --positions
Dump positions of records.
@item -r
@itemx --raw
Print content records in raw format.
@item -s
@itemx --stable
Print content in stable format usable for comparison.
@item -v
@itemx --version
Display the @command{gcov-dump} version number (on the standard output),
and exit without doing any further processing.
@end table
@c man end

267
gcc/doc/gcov-tool.texi Normal file
View File

@ -0,0 +1,267 @@
@c Copyright (C) 2014-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@ignore
@c man begin COPYRIGHT
Copyright @copyright{} 2014-2022 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 ``GNU General Public License'' and ``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 gfdl(7) man page.
(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.
@c man end
@c Set file name and title for the man page.
@setfilename gcov-tool
@settitle offline gcda profile processing tool
@end ignore
@node Gcov-tool
@chapter @command{gcov-tool}---an Offline Gcda Profile Processing Tool
@command{gcov-tool} is a tool you can use in conjunction with GCC to
manipulate or process gcda profile files offline.
@menu
* Gcov-tool Intro:: Introduction to gcov-tool.
* Invoking Gcov-tool:: How to use gcov-tool.
@end menu
@node Gcov-tool Intro
@section Introduction to @command{gcov-tool}
@c man begin DESCRIPTION
@command{gcov-tool} is an offline tool to process gcc's gcda profile files.
Current gcov-tool supports the following functionalities:
@itemize @bullet
@item
merge two sets of profiles with weights.
@item
read a stream of profiles with associated filenames and merge it with a set of
profiles with weights.
@item
read one set of profile and rewrite profile contents. One can scale or
normalize the count values.
@end itemize
Examples of the use cases for this tool are:
@itemize @bullet
@item
Collect the profiles for different set of inputs, and use this tool to merge
them. One can specify the weight to factor in the relative importance of
each input.
@item
Collect profiles from target systems without a filesystem (freestanding
environments). Merge the collected profiles with associated profiles
present on the host system. One can specify the weight to factor in the
relative importance of each input.
@item
Rewrite the profile after removing a subset of the gcda files, while maintaining
the consistency of the summary and the histogram.
@item
It can also be used to debug or libgcov code as the tools shares the majority
code as the runtime library.
@end itemize
Note that for the merging operation, this profile generated offline may
contain slight different values from the online merged profile. Here are
a list of typical differences:
@itemize @bullet
@item
histogram difference: This offline tool recomputes the histogram after merging
the counters. The resulting histogram, therefore, is precise. The online
merging does not have this capability -- the histogram is merged from two
histograms and the result is an approximation.
@item
summary checksum difference: Summary checksum uses a CRC32 operation. The value
depends on the link list order of gcov-info objects. This order is different in
gcov-tool from that in the online merge. It's expected to have different
summary checksums. It does not really matter as the compiler does not use this
checksum anywhere.
@item
value profile counter values difference: Some counter values for value profile
are runtime dependent, like heap addresses. It's normal to see some difference
in these kind of counters.
@end itemize
@c man end
@node Invoking Gcov-tool
@section Invoking @command{gcov-tool}
@smallexample
gcov-tool @r{[}@var{global-options}@r{]} SUB_COMMAND @r{[}@var{sub_command-options}@r{]} @var{profile_dir}
@end smallexample
@command{gcov-tool} accepts the following options:
@ignore
@c man begin SYNOPSIS
gcov-tool [@option{-v}|@option{--version}] [@option{-h}|@option{--help}]
gcov-tool merge [merge-options] @var{directory1} @var{directory2}
[@option{-o}|@option{--output} @var{directory}]
[@option{-v}|@option{--verbose}]
[@option{-w}|@option{--weight} @var{w1,w2}]
gcov-tool merge-stream [merge-stream-options] [@var{file}]
[@option{-v}|@option{--verbose}]
[@option{-w}|@option{--weight} @var{w1,w2}]
gcov-tool rewrite [rewrite-options] @var{directory}
[@option{-n}|@option{--normalize} @var{long_long_value}]
[@option{-o}|@option{--output} @var{directory}]
[@option{-s}|@option{--scale} @var{float_or_simple-frac_value}]
[@option{-v}|@option{--verbose}]
gcov-tool overlap [overlap-options] @var{directory1} @var{directory2}
[@option{-f}|@option{--function}]
[@option{-F}|@option{--fullname}]
[@option{-h}|@option{--hotonly}]
[@option{-o}|@option{--object}]
[@option{-t}|@option{--hot_threshold}] @var{float}
[@option{-v}|@option{--verbose}]
@c man end
@c man begin SEEALSO
gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1) and the Info entry for
@file{gcc}.
@c man end
@end ignore
@c man begin OPTIONS
@table @gcctabopt
@item -h
@itemx --help
Display help about using @command{gcov-tool} (on the standard output), and
exit without doing any further processing.
@item -v
@itemx --version
Display the @command{gcov-tool} version number (on the standard output),
and exit without doing any further processing.
@item merge
Merge two profile directories.
@table @gcctabopt
@item -o @var{directory}
@itemx --output @var{directory}
Set the output profile directory. Default output directory name is
@var{merged_profile}.
@item -v
@itemx --verbose
Set the verbose mode.
@item -w @var{w1},@var{w2}
@itemx --weight @var{w1},@var{w2}
Set the merge weights of the @var{directory1} and @var{directory2},
respectively. The default weights are 1 for both.
@end table
@item merge-stream
Collect profiles with associated filenames from a @emph{gcfn} and @emph{gcda}
data stream. Read the stream from the file specified by @var{file} or from
@file{stdin}. Merge the profiles with associated profiles in the host
filesystem. Apply the optional weights while merging profiles.
For the generation of a @emph{gcfn} and @emph{gcda} data stream on the target
system, please have a look at the @code{__gcov_filename_to_gcfn()} and
@code{__gcov_info_to_gcda()} functions declared in @code{#include <gcov.h>}.
@table @gcctabopt
@item -v
@itemx --verbose
Set the verbose mode.
@item -w @var{w1},@var{w2}
@itemx --weight @var{w1},@var{w2}
Set the merge weights of the profiles from the @emph{gcfn} and @emph{gcda} data
stream and the associated profiles in the host filesystem, respectively. The
default weights are 1 for both.
@end table
@item rewrite
Read the specified profile directory and rewrite to a new directory.
@table @gcctabopt
@item -n @var{long_long_value}
@itemx --normalize <long_long_value>
Normalize the profile. The specified value is the max counter value
in the new profile.
@item -o @var{directory}
@itemx --output @var{directory}
Set the output profile directory. Default output name is @var{rewrite_profile}.
@item -s @var{float_or_simple-frac_value}
@itemx --scale @var{float_or_simple-frac_value}
Scale the profile counters. The specified value can be in floating point value,
or simple fraction value form, such 1, 2, 2/3, and 5/3.
@item -v
@itemx --verbose
Set the verbose mode.
@end table
@item overlap
Compute the overlap score between the two specified profile directories.
The overlap score is computed based on the arc profiles. It is defined as
the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all),
for all arc counter i, where p1_counter[i] and p2_counter[i] are two
matched counters and p1_sum_all and p2_sum_all are the sum of counter
values in profile 1 and profile 2, respectively.
@table @gcctabopt
@item -f
@itemx --function
Print function level overlap score.
@item -F
@itemx --fullname
Print full gcda filename.
@item -h
@itemx --hotonly
Only print info for hot objects/functions.
@item -o
@itemx --object
Print object level overlap score.
@item -t @var{float}
@itemx --hot_threshold <float>
Set the threshold for hot counter value.
@item -v
@itemx --verbose
Set the verbose mode.
@end table
@end table
@c man end

1362
gcc/doc/gcov.texi Normal file
View File

File diff suppressed because it is too large Load Diff

3619
gcc/doc/generic.texi Normal file
View File

File diff suppressed because it is too large Load Diff

2772
gcc/doc/gimple.texi Normal file
View File

File diff suppressed because it is too large Load Diff

20
gcc/doc/gnu.texi Normal file
View File

@ -0,0 +1,20 @@
@c Copyright (C) 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node GNU Project
@unnumbered The GNU Project and GNU/Linux
The GNU Project was launched in 1984 to develop a complete Unix-like
operating system which is free software: the GNU system. (GNU is a
recursive acronym for ``GNU's Not Unix''; it is pronounced
``guh-NEW''@.) Variants of the GNU operating system, which use the
kernel Linux, are now widely used; though these systems are often
referred to as ``Linux'', they are more accurately called GNU/Linux
systems.
For more information, see:
@smallexample
@uref{https://www.gnu.org/}
@uref{https://www.gnu.org/gnu/linux-and-gnu.html}
@end smallexample

735
gcc/doc/gty.texi Normal file
View File

@ -0,0 +1,735 @@
@c Copyright (C) 2002-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Type Information
@chapter Memory Management and Type Information
@cindex GGC
@findex GTY
GCC uses some fairly sophisticated memory management techniques, which
involve determining information about GCC's data structures from GCC's
source code and using this information to perform garbage collection and
implement precompiled headers.
A full C++ parser would be too complicated for this task, so a limited
subset of C++ is interpreted and special markers are used to determine
what parts of the source to look at. All @code{struct}, @code{union}
and @code{template} structure declarations that define data structures
that are allocated under control of the garbage collector must be
marked. All global variables that hold pointers to garbage-collected
memory must also be marked. Finally, all global variables that need
to be saved and restored by a precompiled header must be marked. (The
precompiled header mechanism can only save static variables if they're
scalar. Complex data structures must be allocated in garbage-collected
memory to be saved in a precompiled header.)
The full format of a marker is
@smallexample
GTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{}))
@end smallexample
@noindent
but in most cases no options are needed. The outer double parentheses
are still necessary, though: @code{GTY(())}. Markers can appear:
@itemize @bullet
@item
In a structure definition, before the open brace;
@item
In a global variable declaration, after the keyword @code{static} or
@code{extern}; and
@item
In a structure field definition, before the name of the field.
@end itemize
Here are some examples of marking simple data structures and globals.
@smallexample
struct GTY(()) @var{tag}
@{
@var{fields}@dots{}
@};
typedef struct GTY(()) @var{tag}
@{
@var{fields}@dots{}
@} *@var{typename};
static GTY(()) struct @var{tag} *@var{list}; /* @r{points to GC memory} */
static GTY(()) int @var{counter}; /* @r{save counter in a PCH} */
@end smallexample
The parser understands simple typedefs such as
@code{typedef struct @var{tag} *@var{name};} and
@code{typedef int @var{name};}.
These don't need to be marked.
However, in combination with GTY, avoid using typedefs such as
@code{typedef int_hash<@dots{}> @var{name};}
for these generate infinite-recursion code.
See @uref{https://gcc.gnu.org/PR103157,PR103157}.
Instead, you may use
@code{struct @var{name} : int_hash<@dots{}> @{@};},
for example.
Since @code{gengtype}'s understanding of C++ is limited, there are
several constructs and declarations that are not supported inside
classes/structures marked for automatic GC code generation. The
following C++ constructs produce a @code{gengtype} error on
structures/classes marked for automatic GC code generation:
@itemize @bullet
@item
Type definitions inside classes/structures are not supported.
@item
Enumerations inside classes/structures are not supported.
@end itemize
If you have a class or structure using any of the above constructs,
you need to mark that class as @code{GTY ((user))} and provide your
own marking routines (see section @ref{User GC} for details).
It is always valid to include function definitions inside classes.
Those are always ignored by @code{gengtype}, as it only cares about
data members.
@menu
* GTY Options:: What goes inside a @code{GTY(())}.
* Inheritance and GTY:: Adding GTY to a class hierarchy.
* User GC:: Adding user-provided GC marking routines.
* GGC Roots:: Making global variables GGC roots.
* Files:: How the generated files work.
* Invoking the garbage collector:: How to invoke the garbage collector.
* Troubleshooting:: When something does not work as expected.
@end menu
@node GTY Options
@section The Inside of a @code{GTY(())}
Sometimes the C code is not enough to fully describe the type
structure. Extra information can be provided with @code{GTY} options
and additional markers. Some options take a parameter, which may be
either a string or a type name, depending on the parameter. If an
option takes no parameter, it is acceptable either to omit the
parameter entirely, or to provide an empty string as a parameter. For
example, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} are
equivalent.
When the parameter is a string, often it is a fragment of C code. Four
special escapes may be used in these strings, to refer to pieces of
the data structure being marked:
@cindex % in GTY option
@table @code
@item %h
The current structure.
@item %1
The structure that immediately contains the current structure.
@item %0
The outermost structure that contains the current structure.
@item %a
A partial expression of the form @code{[i1][i2]@dots{}} that indexes
the array item currently being marked.
@end table
For instance, suppose that you have a structure of the form
@smallexample
struct A @{
@dots{}
@};
struct B @{
struct A foo[12];
@};
@end smallexample
@noindent
and @code{b} is a variable of type @code{struct B}. When marking
@samp{b.foo[11]}, @code{%h} would expand to @samp{b.foo[11]},
@code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a}
would expand to @samp{[11]}.
As in ordinary C, adjacent strings will be concatenated; this is
helpful when you have a complicated expression.
@smallexample
@group
GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE"
" ? TYPE_NEXT_VARIANT (&%h.generic)"
" : TREE_CHAIN (&%h.generic)")))
@end group
@end smallexample
The available options are:
@table @code
@findex length
@item length ("@var{expression}")
There are two places the type machinery will need to be explicitly told
the length of an array of non-atomic objects. The first case is when a
structure ends in a variable-length array, like this:
@smallexample
struct GTY(()) rtvec_def @{
int num_elem; /* @r{number of elements} */
rtx GTY ((length ("%h.num_elem"))) elem[1];
@};
@end smallexample
In this case, the @code{length} option is used to override the specified
array length (which should usually be @code{1}). The parameter of the
option is a fragment of C code that calculates the length.
The second case is when a structure or a global variable contains a
pointer to an array, like this:
@smallexample
struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter;
@end smallexample
In this case, @code{iter} has been allocated by writing something like
@smallexample
x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse);
@end smallexample
and the @code{collapse} provides the length of the field.
This second use of @code{length} also works on global variables, like:
@verbatim
static GTY((length("reg_known_value_size"))) rtx *reg_known_value;
@end verbatim
Note that the @code{length} option is only meant for use with arrays of
non-atomic objects, that is, objects that contain pointers pointing to
other GTY-managed objects. For other GC-allocated arrays and strings
you should use @code{atomic} or @code{string_length}.
@findex string_length
@item string_length ("@var{expression}")
In order to simplify production of PCH, a structure member that is a plain
array of bytes (an optionally @code{const} and/or @code{unsigned} @code{char
*}) is treated specially by the infrastructure. Even if such an array has not
been allocated in GC-controlled memory, it will still be written properly into
a PCH. The machinery responsible for this needs to know the length of the
data; by default, the length is determined by calling @code{strlen} on the
pointer. The @code{string_length} option specifies an alternate way to
determine the length, such as by inspecting another struct member:
@smallexample
struct GTY(()) non_terminated_string @{
size_t sz;
const char * GTY((string_length ("%h.sz"))) data;
@};
@end smallexample
@findex skip
@item skip
If @code{skip} is applied to a field, the type machinery will ignore it.
This is somewhat dangerous; the only safe use is in a union when one
field really isn't ever used.
@findex callback
@item callback
@code{callback} should be applied to fields with pointer to function type
and causes the field to be ignored similarly to @code{skip}, except when
writing PCH and the field is non-NULL it will remember the field's address
for relocation purposes if the process writing PCH has different load base
from a process reading PCH.
@findex for_user
@item for_user
Use this to mark types that need to be marked by user gc routines, but are not
refered to in a template argument. So if you have some user gc type T1 and a
non user gc type T2 you can give T2 the for_user option so that the marking
functions for T1 can call non mangled functions to mark T2.
@findex desc
@findex tag
@findex default
@item desc ("@var{expression}")
@itemx tag ("@var{constant}")
@itemx default
The type machinery needs to be told which field of a @code{union} is
currently active. This is done by giving each field a constant
@code{tag} value, and then specifying a discriminator using @code{desc}.
The value of the expression given by @code{desc} is compared against
each @code{tag} value, each of which should be different. If no
@code{tag} is matched, the field marked with @code{default} is used if
there is one, otherwise no field in the union will be marked.
In the @code{desc} option, the ``current structure'' is the union that
it discriminates. Use @code{%1} to mean the structure containing it.
There are no escapes available to the @code{tag} option, since it is a
constant.
For example,
@smallexample
struct GTY(()) tree_binding
@{
struct tree_common common;
union tree_binding_u @{
tree GTY ((tag ("0"))) scope;
struct cp_binding_level * GTY ((tag ("1"))) level;
@} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope;
tree value;
@};
@end smallexample
In this example, the value of BINDING_HAS_LEVEL_P when applied to a
@code{struct tree_binding *} is presumed to be 0 or 1. If 1, the type
mechanism will treat the field @code{level} as being present and if 0,
will treat the field @code{scope} as being present.
The @code{desc} and @code{tag} options can also be used for inheritance
to denote which subclass an instance is. See @ref{Inheritance and GTY}
for more information.
@findex cache
@item cache
When the @code{cache} option is applied to a global variable gt_cleare_cache is
called on that variable between the mark and sweep phases of garbage
collection. The gt_clear_cache function is free to mark blocks as used, or to
clear pointers in the variable.
@findex deletable
@item deletable
@code{deletable}, when applied to a global variable, indicates that when
garbage collection runs, there's no need to mark anything pointed to
by this variable, it can just be set to @code{NULL} instead. This is used
to keep a list of free structures around for re-use.
@findex maybe_undef
@item maybe_undef
When applied to a field, @code{maybe_undef} indicates that it's OK if
the structure that this fields points to is never defined, so long as
this field is always @code{NULL}. This is used to avoid requiring
backends to define certain optional structures. It doesn't work with
language frontends.
@findex nested_ptr
@item nested_ptr (@var{type}, "@var{to expression}", "@var{from expression}")
The type machinery expects all pointers to point to the start of an
object. Sometimes for abstraction purposes it's convenient to have
a pointer which points inside an object. So long as it's possible to
convert the original object to and from the pointer, such pointers
can still be used. @var{type} is the type of the original object,
the @var{to expression} returns the pointer given the original object,
and the @var{from expression} returns the original object given
the pointer. The pointer will be available using the @code{%h}
escape.
@findex chain_next
@findex chain_prev
@findex chain_circular
@item chain_next ("@var{expression}")
@itemx chain_prev ("@var{expression}")
@itemx chain_circular ("@var{expression}")
It's helpful for the type machinery to know if objects are often
chained together in long lists; this lets it generate code that uses
less stack space by iterating along the list instead of recursing down
it. @code{chain_next} is an expression for the next item in the list,
@code{chain_prev} is an expression for the previous item. For singly
linked lists, use only @code{chain_next}; for doubly linked lists, use
both. The machinery requires that taking the next item of the
previous item gives the original item. @code{chain_circular} is similar
to @code{chain_next}, but can be used for circular single linked lists.
@findex reorder
@item reorder ("@var{function name}")
Some data structures depend on the relative ordering of pointers. If
the precompiled header machinery needs to change that ordering, it
will call the function referenced by the @code{reorder} option, before
changing the pointers in the object that's pointed to by the field the
option applies to. The function must take four arguments, with the
signature @samp{@w{void *, void *, gt_pointer_operator, void *}}.
The first parameter is a pointer to the structure that contains the
object being updated, or the object itself if there is no containing
structure. The second parameter is a cookie that should be ignored.
The third parameter is a routine that, given a pointer, will update it
to its correct new value. The fourth parameter is a cookie that must
be passed to the second parameter.
PCH cannot handle data structures that depend on the absolute values
of pointers. @code{reorder} functions can be expensive. When
possible, it is better to depend on properties of the data, like an ID
number or the hash of a string instead.
@findex atomic
@item atomic
The @code{atomic} option can only be used with pointers. It informs
the GC machinery that the memory that the pointer points to does not
contain any pointers, and hence it should be treated by the GC and PCH
machinery as an ``atomic'' block of memory that does not need to be
examined when scanning memory for pointers. In particular, the
machinery will not scan that memory for pointers to mark them as
reachable (when marking pointers for GC) or to relocate them (when
writing a PCH file).
The @code{atomic} option differs from the @code{skip} option.
@code{atomic} keeps the memory under Garbage Collection, but makes the
GC ignore the contents of the memory. @code{skip} is more drastic in
that it causes the pointer and the memory to be completely ignored by
the Garbage Collector. So, memory marked as @code{atomic} is
automatically freed when no longer reachable, while memory marked as
@code{skip} is not.
The @code{atomic} option must be used with great care, because all
sorts of problem can occur if used incorrectly, that is, if the memory
the pointer points to does actually contain a pointer.
Here is an example of how to use it:
@smallexample
struct GTY(()) my_struct @{
int number_of_elements;
unsigned int * GTY ((atomic)) elements;
@};
@end smallexample
In this case, @code{elements} is a pointer under GC, and the memory it
points to needs to be allocated using the Garbage Collector, and will
be freed automatically by the Garbage Collector when it is no longer
referenced. But the memory that the pointer points to is an array of
@code{unsigned int} elements, and the GC must not try to scan it to
find pointers to mark or relocate, which is why it is marked with the
@code{atomic} option.
Note that, currently, global variables cannot be marked with
@code{atomic}; only fields of a struct can. This is a known
limitation. It would be useful to be able to mark global pointers
with @code{atomic} to make the PCH machinery aware of them so that
they are saved and restored correctly to PCH files.
@findex special
@item special ("@var{name}")
The @code{special} option is used to mark types that have to be dealt
with by special case machinery. The parameter is the name of the
special case. See @file{gengtype.cc} for further details. Avoid
adding new special cases unless there is no other alternative.
@findex user
@item user
The @code{user} option indicates that the code to mark structure
fields is completely handled by user-provided routines. See section
@ref{User GC} for details on what functions need to be provided.
@end table
@node Inheritance and GTY
@section Support for inheritance
gengtype has some support for simple class hierarchies. You can use
this to have gengtype autogenerate marking routines, provided:
@itemize @bullet
@item
There must be a concrete base class, with a discriminator expression
that can be used to identify which subclass an instance is.
@item
Only single inheritance is used.
@item
None of the classes within the hierarchy are templates.
@end itemize
If your class hierarchy does not fit in this pattern, you must use
@ref{User GC} instead.
The base class and its discriminator must be identified using the ``desc''
option. Each concrete subclass must use the ``tag'' option to identify
which value of the discriminator it corresponds to.
Every class in the hierarchy must have a @code{GTY(())} marker, as
gengtype will only attempt to parse classes that have such a marker
@footnote{Classes lacking such a marker will not be identified as being
part of the hierarchy, and so the marking routines will not handle them,
leading to a assertion failure within the marking routines due to an
unknown tag value (assuming that assertions are enabled).}.
@smallexample
class GTY((desc("%h.kind"), tag("0"))) example_base
@{
public:
int kind;
tree a;
@};
class GTY((tag("1"))) some_subclass : public example_base
@{
public:
tree b;
@};
class GTY((tag("2"))) some_other_subclass : public example_base
@{
public:
tree c;
@};
@end smallexample
The generated marking routines for the above will contain a ``switch''
on ``kind'', visiting all appropriate fields. For example, if kind is
2, it will cast to ``some_other_subclass'' and visit fields a, b, and c.
@node User GC
@section Support for user-provided GC marking routines
@cindex user gc
The garbage collector supports types for which no automatic marking
code is generated. For these types, the user is required to provide
three functions: one to act as a marker for garbage collection, and
two functions to act as marker and pointer walker for pre-compiled
headers.
Given a structure @code{struct GTY((user)) my_struct}, the following functions
should be defined to mark @code{my_struct}:
@smallexample
void gt_ggc_mx (my_struct *p)
@{
/* This marks field 'fld'. */
gt_ggc_mx (p->fld);
@}
void gt_pch_nx (my_struct *p)
@{
/* This marks field 'fld'. */
gt_pch_nx (tp->fld);
@}
void gt_pch_nx (my_struct *p, gt_pointer_operator op, void *cookie)
@{
/* For every field 'fld', call the given pointer operator. */
op (&(tp->fld), NULL, cookie);
@}
@end smallexample
In general, each marker @code{M} should call @code{M} for every
pointer field in the structure. Fields that are not allocated in GC
or are not pointers must be ignored.
For embedded lists (e.g., structures with a @code{next} or @code{prev}
pointer), the marker must follow the chain and mark every element in
it.
Note that the rules for the pointer walker @code{gt_pch_nx (my_struct
*, gt_pointer_operator, void *)} are slightly different. In this
case, the operation @code{op} must be applied to the @emph{address} of
every pointer field.
@subsection User-provided marking routines for template types
When a template type @code{TP} is marked with @code{GTY}, all
instances of that type are considered user-provided types. This means
that the individual instances of @code{TP} do not need to be marked
with @code{GTY}. The user needs to provide template functions to mark
all the fields of the type.
The following code snippets represent all the functions that need to
be provided. Note that type @code{TP} may reference to more than one
type. In these snippets, there is only one type @code{T}, but there
could be more.
@smallexample
template<typename T>
void gt_ggc_mx (TP<T> *tp)
@{
extern void gt_ggc_mx (T&);
/* This marks field 'fld' of type 'T'. */
gt_ggc_mx (tp->fld);
@}
template<typename T>
void gt_pch_nx (TP<T> *tp)
@{
extern void gt_pch_nx (T&);
/* This marks field 'fld' of type 'T'. */
gt_pch_nx (tp->fld);
@}
template<typename T>
void gt_pch_nx (TP<T *> *tp, gt_pointer_operator op, void *cookie)
@{
/* For every field 'fld' of 'tp' with type 'T *', call the given
pointer operator. */
op (&(tp->fld), NULL, cookie);
@}
template<typename T>
void gt_pch_nx (TP<T> *tp, gt_pointer_operator, void *cookie)
@{
extern void gt_pch_nx (T *, gt_pointer_operator, void *);
/* For every field 'fld' of 'tp' with type 'T', call the pointer
walker for all the fields of T. */
gt_pch_nx (&(tp->fld), op, cookie);
@}
@end smallexample
Support for user-defined types is currently limited. The following
restrictions apply:
@enumerate
@item Type @code{TP} and all the argument types @code{T} must be
marked with @code{GTY}.
@item Type @code{TP} can only have type names in its argument list.
@item The pointer walker functions are different for @code{TP<T>} and
@code{TP<T *>}. In the case of @code{TP<T>}, references to
@code{T} must be handled by calling @code{gt_pch_nx} (which
will, in turn, walk all the pointers inside fields of @code{T}).
In the case of @code{TP<T *>}, references to @code{T *} must be
handled by calling the @code{op} function on the address of the
pointer (see the code snippets above).
@end enumerate
@node GGC Roots
@section Marking Roots for the Garbage Collector
@cindex roots, marking
@cindex marking roots
In addition to keeping track of types, the type machinery also locates
the global variables (@dfn{roots}) that the garbage collector starts
at. Roots must be declared using one of the following syntaxes:
@itemize @bullet
@item
@code{extern GTY(([@var{options}])) @var{type} @var{name};}
@item
@code{static GTY(([@var{options}])) @var{type} @var{name};}
@end itemize
@noindent
The syntax
@itemize @bullet
@item
@code{GTY(([@var{options}])) @var{type} @var{name};}
@end itemize
@noindent
is @emph{not} accepted. There should be an @code{extern} declaration
of such a variable in a header somewhere---mark that, not the
definition. Or, if the variable is only used in one file, make it
@code{static}.
@node Files
@section Source Files Containing Type Information
@cindex generated files
@cindex files, generated
Whenever you add @code{GTY} markers to a source file that previously
had none, or create a new source file containing @code{GTY} markers,
there are three things you need to do:
@enumerate
@item
You need to add the file to the list of source files the type
machinery scans. There are four cases:
@enumerate a
@item
For a back-end file, this is usually done
automatically; if not, you should add it to @code{target_gtfiles} in
the appropriate port's entries in @file{config.gcc}.
@item
For files shared by all front ends, add the filename to the
@code{GTFILES} variable in @file{Makefile.in}.
@item
For files that are part of one front end, add the filename to the
@code{gtfiles} variable defined in the appropriate
@file{config-lang.in}.
Headers should appear before non-headers in this list.
@item
For files that are part of some but not all front ends, add the
filename to the @code{gtfiles} variable of @emph{all} the front ends
that use it.
@end enumerate
@item
If the file was a header file, you'll need to check that it's included
in the right place to be visible to the generated files. For a back-end
header file, this should be done automatically. For a front-end header
file, it needs to be included by the same file that includes
@file{gtype-@var{lang}.h}. For other header files, it needs to be
included in @file{gtype-desc.cc}, which is a generated file, so add it to
@code{ifiles} in @code{open_base_file} in @file{gengtype.cc}.
For source files that aren't header files, the machinery will generate a
header file that should be included in the source file you just changed.
The file will be called @file{gt-@var{path}.h} where @var{path} is the
pathname relative to the @file{gcc} directory with slashes replaced by
@verb{|-|}, so for example the header file to be included in
@file{cp/parser.cc} is called @file{gt-cp-parser.h}. The
generated header file should be included after everything else in the
source file.
@end enumerate
For language frontends, there is another file that needs to be included
somewhere. It will be called @file{gtype-@var{lang}.h}, where
@var{lang} is the name of the subdirectory the language is contained in.
Plugins can add additional root tables. Run the @code{gengtype}
utility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir}
@var{file-list} @var{plugin*.c}} with your plugin files
@var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file.
The GCC build tree is needed to be present in that mode.
@node Invoking the garbage collector
@section How to invoke the garbage collector
@cindex garbage collector, invocation
@findex ggc_collect
The GCC garbage collector GGC is only invoked explicitly. In contrast
with many other garbage collectors, it is not implicitly invoked by
allocation routines when a lot of memory has been consumed. So the
only way to have GGC reclaim storage is to call the @code{ggc_collect}
function explicitly.
With @var{mode} @code{GGC_COLLECT_FORCE} or otherwise (default
@code{GGC_COLLECT_HEURISTIC}) when the internal heuristic decides to
collect, this call is potentially an expensive operation, as it may
have to scan the entire heap. Beware that local variables (on the GCC
call stack) are not followed by such an invocation (as many other
garbage collectors do): you should reference all your data from static
or external @code{GTY}-ed variables, and it is advised to call
@code{ggc_collect} with a shallow call stack. The GGC is an exact mark
and sweep garbage collector (so it does not scan the call stack for
pointers). In practice GCC passes don't often call @code{ggc_collect}
themselves, because it is called by the pass manager between passes.
At the time of the @code{ggc_collect} call all pointers in the GC-marked
structures must be valid or @code{NULL}. In practice this means that
there should not be uninitialized pointer fields in the structures even
if your code never reads or writes those fields at a particular
instance. One way to ensure this is to use cleared versions of
allocators unless all the fields are initialized manually immediately
after allocation.
@node Troubleshooting
@section Troubleshooting the garbage collector
@cindex garbage collector, troubleshooting
With the current garbage collector implementation, most issues should
show up as GCC compilation errors. Some of the most commonly
encountered issues are described below.
@itemize @bullet
@item Gengtype does not produce allocators for a @code{GTY}-marked type.
Gengtype checks if there is at least one possible path from GC roots to
at least one instance of each type before outputting allocators. If
there is no such path, the @code{GTY} markers will be ignored and no
allocators will be output. Solve this by making sure that there exists
at least one such path. If creating it is unfeasible or raises a ``code
smell'', consider if you really must use GC for allocating such type.
@item Link-time errors about undefined @code{gt_ggc_r_foo_bar} and
similarly-named symbols. Check if your @file{foo_bar} source file has
@code{#include "gt-foo_bar.h"} as its very last line.
@end itemize

32
gcc/doc/headerdirs.texi Normal file
View File

@ -0,0 +1,32 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Header Dirs
@chapter Standard Header File Directories
@code{GCC_INCLUDE_DIR} means the same thing for native and cross. It is
where GCC stores its private include files, and also where GCC
stores the fixed include files. A cross compiled GCC runs
@code{fixincludes} on the header files in @file{$(tooldir)/include}.
(If the cross compilation header files need to be fixed, they must be
installed before GCC is built. If the cross compilation header files
are already suitable for GCC, nothing special need be done).
@code{GPLUSPLUS_INCLUDE_DIR} means the same thing for native and cross. It
is where @command{g++} looks first for header files. The C++ library
installs only target independent header files in that directory.
@code{LOCAL_INCLUDE_DIR} is used only by native compilers. GCC
doesn't install anything there. It is normally
@file{/usr/local/include}. This is where local additions to a packaged
system should place header files.
@code{CROSS_INCLUDE_DIR} is used only by cross compilers. GCC
doesn't install anything there.
@code{TOOL_INCLUDE_DIR} is used for both native and cross compilers. It
is the place for other packages to install header files that GCC will
use. For a cross-compiler, this is the equivalent of
@file{/usr/include}. When you build a cross-compiler,
@code{fixincludes} processes any header files in this directory.

229
gcc/doc/hostconfig.texi Normal file
View File

@ -0,0 +1,229 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gccint.texi.
@node Host Config
@chapter Host Configuration
@cindex host configuration
Most details about the machine and system on which the compiler is
actually running are detected by the @command{configure} script. Some
things are impossible for @command{configure} to detect; these are
described in two ways, either by macros defined in a file named
@file{xm-@var{machine}.h} or by hook functions in the file specified
by the @var{out_host_hook_obj} variable in @file{config.gcc}. (The
intention is that very few hosts will need a header file but nearly
every fully supported host will need to override some hooks.)
If you need to define only a few macros, and they have simple
definitions, consider using the @code{xm_defines} variable in your
@file{config.gcc} entry instead of creating a host configuration
header. @xref{System Config}.
@menu
* Host Common:: Things every host probably needs implemented.
* Filesystem:: Your host cannot have the letter `a' in filenames?
* Host Misc:: Rare configuration options for hosts.
@end menu
@node Host Common
@section Host Common
@cindex host hooks
@cindex host functions
Some things are just not portable, even between similar operating systems,
and are too difficult for autoconf to detect. They get implemented using
hook functions in the file specified by the @var{host_hook_obj}
variable in @file{config.gcc}.
@deftypefn {Host Hook} void HOST_HOOKS_EXTRA_SIGNALS (void)
This host hook is used to set up handling for extra signals. The most
common thing to do in this hook is to detect stack overflow.
@end deftypefn
@deftypefn {Host Hook} {void *} HOST_HOOKS_GT_PCH_GET_ADDRESS (size_t @
@var{size}, int @var{fd})
This host hook returns the address of some space that is likely to be
free in some subsequent invocation of the compiler. We intend to load
the PCH data at this address such that the data need not be relocated.
The area should be able to hold @var{size} bytes. If the host uses
@code{mmap}, @var{fd} is an open file descriptor that can be used for
probing.
@end deftypefn
@deftypefn {Host Hook} int HOST_HOOKS_GT_PCH_USE_ADDRESS (void * @var{address}, @
size_t @var{size}, int @var{fd}, size_t @var{offset})
This host hook is called when a PCH file is about to be loaded.
We want to load @var{size} bytes from @var{fd} at @var{offset}
into memory at @var{address}. The given address will be the result of
a previous invocation of @code{HOST_HOOKS_GT_PCH_GET_ADDRESS}.
Return @minus{}1 if we couldn't allocate @var{size} bytes at @var{address}.
Return 0 if the memory is allocated but the data is not loaded. Return 1
if the hook has performed everything.
If the implementation uses reserved address space, free any reserved
space beyond @var{size}, regardless of the return value. If no PCH will
be loaded, this hook may be called with @var{size} zero, in which case
all reserved address space should be freed.
Do not try to handle values of @var{address} that could not have been
returned by this executable; just return @minus{}1. Such values usually
indicate an out-of-date PCH file (built by some other GCC executable),
and such a PCH file won't work.
@end deftypefn
@deftypefn {Host Hook} size_t HOST_HOOKS_GT_PCH_ALLOC_GRANULARITY (void);
This host hook returns the alignment required for allocating virtual
memory. Usually this is the same as getpagesize, but on some hosts the
alignment for reserving memory differs from the pagesize for committing
memory.
@end deftypefn
@node Filesystem
@section Host Filesystem
@cindex configuration file
@cindex @file{xm-@var{machine}.h}
GCC needs to know a number of things about the semantics of the host
machine's filesystem. Filesystems with Unix and MS-DOS semantics are
automatically detected. For other systems, you can define the
following macros in @file{xm-@var{machine}.h}.
@ftable @code
@item HAVE_DOS_BASED_FILE_SYSTEM
This macro is automatically defined by @file{system.h} if the host
file system obeys the semantics defined by MS-DOS instead of Unix.
DOS file systems are case insensitive, file specifications may begin
with a drive letter, and both forward slash and backslash (@samp{/}
and @samp{\}) are directory separators.
@item DIR_SEPARATOR
@itemx DIR_SEPARATOR_2
If defined, these macros expand to character constants specifying
separators for directory names within a file specification.
@file{system.h} will automatically give them appropriate values on
Unix and MS-DOS file systems. If your file system is neither of
these, define one or both appropriately in @file{xm-@var{machine}.h}.
However, operating systems like VMS, where constructing a pathname is
more complicated than just stringing together directory names
separated by a special character, should not define either of these
macros.
@item PATH_SEPARATOR
If defined, this macro should expand to a character constant
specifying the separator for elements of search paths. The default
value is a colon (@samp{:}). DOS-based systems usually, but not
always, use semicolon (@samp{;}).
@item VMS
Define this macro if the host system is VMS@.
@item HOST_OBJECT_SUFFIX
Define this macro to be a C string representing the suffix for object
files on your host machine. If you do not define this macro, GCC will
use @samp{.o} as the suffix for object files.
@item HOST_EXECUTABLE_SUFFIX
Define this macro to be a C string representing the suffix for
executable files on your host machine. If you do not define this macro,
GCC will use the null string as the suffix for executable files.
@item HOST_BIT_BUCKET
A pathname defined by the host operating system, which can be opened as
a file and written to, but all the information written is discarded.
This is commonly known as a @dfn{bit bucket} or @dfn{null device}. If
you do not define this macro, GCC will use @samp{/dev/null} as the bit
bucket. If the host does not support a bit bucket, define this macro to
an invalid filename.
@item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
If defined, a C statement (sans semicolon) that performs host-dependent
canonicalization when a path used in a compilation driver or
preprocessor is canonicalized. @var{path} is a malloc-ed path to be
canonicalized. If the C statement does canonicalize @var{path} into a
different buffer, the old path should be freed and the new buffer should
have been allocated with malloc.
@item DUMPFILE_FORMAT
Define this macro to be a C string representing the format to use for
constructing the index part of debugging dump file names. The resultant
string must fit in fifteen bytes. The full filename will be the
concatenation of: the prefix of the assembler file name, the string
resulting from applying this format to an index number, and a string
unique to each dump file kind, e.g.@: @samp{rtl}.
If you do not define this macro, GCC will use @samp{.%02d.}. You should
define this macro if using the default will create an invalid file name.
@item DELETE_IF_ORDINARY
Define this macro to be a C statement (sans semicolon) that performs
host-dependent removal of ordinary temp files in the compilation driver.
If you do not define this macro, GCC will use the default version. You
should define this macro if the default version does not reliably remove
the temp file as, for example, on VMS which allows multiple versions
of a file.
@item HOST_LACKS_INODE_NUMBERS
Define this macro if the host filesystem does not report meaningful inode
numbers in struct stat.
@end ftable
@node Host Misc
@section Host Misc
@cindex configuration file
@cindex @file{xm-@var{machine}.h}
@ftable @code
@item FATAL_EXIT_CODE
A C expression for the status code to be returned when the compiler
exits after serious errors. The default is the system-provided macro
@samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
macro. Define this macro only if these defaults are incorrect.
@item SUCCESS_EXIT_CODE
A C expression for the status code to be returned when the compiler
exits without serious errors. (Warnings are not serious errors.) The
default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
the system doesn't define that macro. Define this macro only if these
defaults are incorrect.
@item USE_C_ALLOCA
Define this macro if GCC should use the C implementation of @code{alloca}
provided by @file{libiberty.a}. This only affects how some parts of the
compiler itself allocate memory. It does not change code generation.
When GCC is built with a compiler other than itself, the C @code{alloca}
is always used. This is because most other implementations have serious
bugs. You should define this macro only on a system where no
stack-based @code{alloca} can possibly work. For instance, if a system
has a small limit on the size of the stack, GCC's builtin @code{alloca}
will not work reliably.
@item COLLECT2_HOST_INITIALIZATION
If defined, a C statement (sans semicolon) that performs host-dependent
initialization when @code{collect2} is being initialized.
@item GCC_DRIVER_HOST_INITIALIZATION
If defined, a C statement (sans semicolon) that performs host-dependent
initialization when a compilation driver is being initialized.
@item HOST_LONG_LONG_FORMAT
If defined, the string used to indicate an argument of type @code{long
long} to functions like @code{printf}. The default value is
@code{"ll"}.
@item HOST_LONG_FORMAT
If defined, the string used to indicate an argument of type @code{long}
to functions like @code{printf}. The default value is @code{"l"}.
@item HOST_PTR_PRINTF
If defined, the string used to indicate an argument of type @code{void *}
to functions like @code{printf}. The default value is @code{"%p"}.
@end ftable
In addition, if @command{configure} generates an incorrect definition of
any of the macros in @file{auto-host.h}, you can override that
definition in a host configuration header. If you need to do this,
first see if it is possible to fix @command{configure}.

746
gcc/doc/implement-c.texi Normal file
View File

@ -0,0 +1,746 @@
@c Copyright (C) 2001-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node C Implementation
@chapter C Implementation-Defined Behavior
@cindex implementation-defined behavior, C language
A conforming implementation of ISO C is required to document its
choice of behavior in each of the areas that are designated
``implementation defined''. The following lists all such areas,
along with the section numbers from the ISO/IEC 9899:1990, ISO/IEC
9899:1999 and ISO/IEC 9899:2011 standards. Some areas are only
implementation-defined in one version of the standard.
Some choices depend on the externally determined ABI for the platform
(including standard character encodings) which GCC follows; these are
listed as ``determined by ABI'' below. @xref{Compatibility, , Binary
Compatibility}, and @uref{https://gcc.gnu.org/readings.html}. Some
choices are documented in the preprocessor manual.
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}. Some choices are made by the
library and operating system (or other environment when compiling for
a freestanding environment); refer to their documentation for details.
@menu
* Translation implementation::
* Environment implementation::
* Identifiers implementation::
* Characters implementation::
* Integers implementation::
* Floating point implementation::
* Arrays and pointers implementation::
* Hints implementation::
* Structures unions enumerations and bit-fields implementation::
* Qualifiers implementation::
* Declarators implementation::
* Statements implementation::
* Preprocessing directives implementation::
* Library functions implementation::
* Architecture implementation::
* Locale-specific behavior implementation::
@end menu
@node Translation implementation
@section Translation
@itemize @bullet
@item
@cite{How a diagnostic is identified (C90 3.7, C99 and C11 3.10, C90,
C99 and C11 5.1.1.3).}
Diagnostics consist of all the output sent to stderr by GCC@.
@item
@cite{Whether each nonempty sequence of white-space characters other than
new-line is retained or replaced by one space character in translation
phase 3 (C90, C99 and C11 5.1.1.2).}
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}.
@end itemize
@node Environment implementation
@section Environment
The behavior of most of these points are dependent on the implementation
of the C library, and are not defined by GCC itself.
@itemize @bullet
@item
@cite{The mapping between physical source file multibyte characters
and the source character set in translation phase 1 (C90, C99 and C11
5.1.1.2).}
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}.
@end itemize
@node Identifiers implementation
@section Identifiers
@itemize @bullet
@item
@cite{Which additional multibyte characters may appear in identifiers
and their correspondence to universal character names (C99 and C11 6.4.2).}
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}.
@item
@cite{The number of significant initial characters in an identifier
(C90 6.1.2, C90, C99 and C11 5.2.4.1, C99 and C11 6.4.2).}
For internal names, all characters are significant. For external names,
the number of significant characters are defined by the linker; for
almost all targets, all characters are significant.
@item
@cite{Whether case distinctions are significant in an identifier with
external linkage (C90 6.1.2).}
This is a property of the linker. C99 and C11 require that case distinctions
are always significant in identifiers with external linkage and
systems without this property are not supported by GCC@.
@end itemize
@node Characters implementation
@section Characters
@itemize @bullet
@item
@cite{The number of bits in a byte (C90 3.4, C99 and C11 3.6).}
Determined by ABI@.
@item
@cite{The values of the members of the execution character set (C90,
C99 and C11 5.2.1).}
Determined by ABI@.
@item
@cite{The unique value of the member of the execution character set produced
for each of the standard alphabetic escape sequences (C90, C99 and C11
5.2.2).}
Determined by ABI@.
@item
@cite{The value of a @code{char} object into which has been stored any
character other than a member of the basic execution character set
(C90 6.1.2.5, C99 and C11 6.2.5).}
Determined by ABI@.
@item
@cite{Which of @code{signed char} or @code{unsigned char} has the same
range, representation, and behavior as ``plain'' @code{char} (C90
6.1.2.5, C90 6.2.1.1, C99 and C11 6.2.5, C99 and C11 6.3.1.1).}
@opindex fsigned-char
@opindex funsigned-char
Determined by ABI@. The options @option{-funsigned-char} and
@option{-fsigned-char} change the default. @xref{C Dialect Options, ,
Options Controlling C Dialect}.
@item
@cite{The mapping of members of the source character set (in character
constants and string literals) to members of the execution character
set (C90 6.1.3.4, C99 and C11 6.4.4.4, C90, C99 and C11 5.1.1.2).}
Determined by ABI@.
@item
@cite{The value of an integer character constant containing more than one
character or containing a character or escape sequence that does not map
to a single-byte execution character (C90 6.1.3.4, C99 and C11 6.4.4.4).}
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}.
@item
@cite{The value of a wide character constant containing more than one
multibyte character or a single multibyte character that maps to
multiple members of the extended execution character set, or
containing a multibyte character or escape sequence not represented in
the extended execution character set (C90 6.1.3.4, C99 and C11
6.4.4.4).}
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}.
@item
@cite{The current locale used to convert a wide character constant consisting
of a single multibyte character that maps to a member of the extended
execution character set into a corresponding wide character code (C90
6.1.3.4, C99 and C11 6.4.4.4).}
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}.
@item
@cite{Whether differently-prefixed wide string literal tokens can be
concatenated and, if so, the treatment of the resulting multibyte
character sequence (C11 6.4.5).}
Such tokens may not be concatenated.
@item
@cite{The current locale used to convert a wide string literal into
corresponding wide character codes (C90 6.1.4, C99 and C11 6.4.5).}
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}.
@item
@cite{The value of a string literal containing a multibyte character or escape
sequence not represented in the execution character set (C90 6.1.4,
C99 and C11 6.4.5).}
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}.
@item
@cite{The encoding of any of @code{wchar_t}, @code{char16_t}, and
@code{char32_t} where the corresponding standard encoding macro
(@code{__STDC_ISO_10646__}, @code{__STDC_UTF_16__}, or
@code{__STDC_UTF_32__}) is not defined (C11 6.10.8.2).}
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}. @code{char16_t} and
@code{char32_t} literals are always encoded in UTF-16 and UTF-32
respectively.
@end itemize
@node Integers implementation
@section Integers
@itemize @bullet
@item
@cite{Any extended integer types that exist in the implementation (C99
and C11 6.2.5).}
GCC does not support any extended integer types.
@c The __mode__ attribute might create types of precisions not
@c otherwise supported, but the syntax isn't right for use everywhere
@c the standard type names might be used. Predefined typedefs should
@c be used if any extended integer types are to be defined. The
@c __int128_t and __uint128_t typedefs are not extended integer types
@c as they are generally longer than the ABI-specified intmax_t.
@item
@cite{Whether signed integer types are represented using sign and magnitude,
two's complement, or one's complement, and whether the extraordinary value
is a trap representation or an ordinary value (C99 and C11 6.2.6.2).}
GCC supports only two's complement integer types, and all bit patterns
are ordinary values.
@item
@cite{The rank of any extended integer type relative to another extended
integer type with the same precision (C99 and C11 6.3.1.1).}
GCC does not support any extended integer types.
@c If it did, there would only be one of each precision and signedness.
@item
@cite{The result of, or the signal raised by, converting an integer to a
signed integer type when the value cannot be represented in an object of
that type (C90 6.2.1.2, C99 and C11 6.3.1.3).}
For conversion to a type of width @math{N}, the value is reduced
modulo @math{2^N} to be within range of the type; no signal is raised.
@item
@cite{The results of some bitwise operations on signed integers (C90
6.3, C99 and C11 6.5).}
Bitwise operators act on the representation of the value including
both the sign and value bits, where the sign bit is considered
immediately above the highest-value value bit. Signed @samp{>>} acts
on negative numbers by sign extension.
As an extension to the C language, GCC does not use the latitude given in
C99 and C11 only to treat certain aspects of signed @samp{<<} as undefined.
However, @option{-fsanitize=shift} (and @option{-fsanitize=undefined}) will
diagnose such cases. They are also diagnosed where constant
expressions are required.
@item
@cite{The sign of the remainder on integer division (C90 6.3.5).}
GCC always follows the C99 and C11 requirement that the result of division is
truncated towards zero.
@end itemize
@node Floating point implementation
@section Floating Point
@itemize @bullet
@item
@cite{The accuracy of the floating-point operations and of the library
functions in @code{<math.h>} and @code{<complex.h>} that return floating-point
results (C90, C99 and C11 5.2.4.2.2).}
The accuracy is unknown.
@item
@cite{The rounding behaviors characterized by non-standard values
of @code{FLT_ROUNDS} @gol
(C90, C99 and C11 5.2.4.2.2).}
GCC does not use such values.
@item
@cite{The evaluation methods characterized by non-standard negative
values of @code{FLT_EVAL_METHOD} (C99 and C11 5.2.4.2.2).}
GCC does not use such values.
@item
@cite{The direction of rounding when an integer is converted to a
floating-point number that cannot exactly represent the original
value (C90 6.2.1.3, C99 and C11 6.3.1.4).}
C99 Annex F is followed.
@item
@cite{The direction of rounding when a floating-point number is
converted to a narrower floating-point number (C90 6.2.1.4, C99 and C11
6.3.1.5).}
C99 Annex F is followed.
@item
@cite{How the nearest representable value or the larger or smaller
representable value immediately adjacent to the nearest representable
value is chosen for certain floating constants (C90 6.1.3.1, C99 and C11
6.4.4.2).}
C99 Annex F is followed.
@item
@cite{Whether and how floating expressions are contracted when not
disallowed by the @code{FP_CONTRACT} pragma (C99 and C11 6.5).}
Expressions are currently only contracted if @option{-ffp-contract=fast},
@option{-funsafe-math-optimizations} or @option{-ffast-math} are used.
This is subject to change.
@item
@cite{The default state for the @code{FENV_ACCESS} pragma (C99 and C11
7.6.1).}
This pragma is not implemented, but the default is to ``off'' unless
@option{-frounding-math} is used and @option{-fno-trapping-math} is not
in which case it is ``on''.
@item
@cite{Additional floating-point exceptions, rounding modes, environments,
and classifications, and their macro names (C99 and C11 7.6, C99 and
C11 7.12).}
This is dependent on the implementation of the C library, and is not
defined by GCC itself.
@item
@cite{The default state for the @code{FP_CONTRACT} pragma (C99 and C11
7.12.2).}
This pragma is not implemented. Expressions are currently only
contracted if @option{-ffp-contract=fast},
@option{-funsafe-math-optimizations} or @option{-ffast-math} are used.
This is subject to change.
@item
@cite{Whether the ``inexact'' floating-point exception can be raised
when the rounded result actually does equal the mathematical result
in an IEC 60559 conformant implementation (C99 F.9).}
This is dependent on the implementation of the C library, and is not
defined by GCC itself.
@item
@cite{Whether the ``underflow'' (and ``inexact'') floating-point
exception can be raised when a result is tiny but not inexact in an
IEC 60559 conformant implementation (C99 F.9).}
This is dependent on the implementation of the C library, and is not
defined by GCC itself.
@end itemize
@node Arrays and pointers implementation
@section Arrays and Pointers
@itemize @bullet
@item
@cite{The result of converting a pointer to an integer or
vice versa (C90 6.3.4, C99 and C11 6.3.2.3).}
A cast from pointer to integer discards most-significant bits if the
pointer representation is larger than the integer type,
sign-extends@footnote{Future versions of GCC may zero-extend, or use
a target-defined @code{ptr_extend} pattern. Do not rely on sign extension.}
if the pointer representation is smaller than the integer type, otherwise
the bits are unchanged.
@c ??? We've always claimed that pointers were unsigned entities.
@c Shouldn't we therefore be doing zero-extension? If so, the bug
@c is in convert_to_integer, where we call type_for_size and request
@c a signed integral type. On the other hand, it might be most useful
@c for the target if we extend according to POINTERS_EXTEND_UNSIGNED.
A cast from integer to pointer discards most-significant bits if the
pointer representation is smaller than the integer type, extends according
to the signedness of the integer type if the pointer representation
is larger than the integer type, otherwise the bits are unchanged.
When casting from pointer to integer and back again, the resulting
pointer must reference the same object as the original pointer, otherwise
the behavior is undefined. That is, one may not use integer arithmetic to
avoid the undefined behavior of pointer arithmetic as proscribed in
C99 and C11 6.5.6/8.
@item
@cite{The size of the result of subtracting two pointers to elements
of the same array (C90 6.3.6, C99 and C11 6.5.6).}
The value is as specified in the standard and the type is determined
by the ABI@.
@end itemize
@node Hints implementation
@section Hints
@itemize @bullet
@item
@cite{The extent to which suggestions made by using the @code{register}
storage-class specifier are effective (C90 6.5.1, C99 and C11 6.7.1).}
The @code{register} specifier affects code generation only in these ways:
@itemize @bullet
@item
When used as part of the register variable extension, see
@ref{Explicit Register Variables}.
@item
When @option{-O0} is in use, the compiler allocates distinct stack
memory for all variables that do not have the @code{register}
storage-class specifier; if @code{register} is specified, the variable
may have a shorter lifespan than the code would indicate and may never
be placed in memory.
@item
On some rare x86 targets, @code{setjmp} doesn't save the registers in
all circumstances. In those cases, GCC doesn't allocate any variables
in registers unless they are marked @code{register}.
@end itemize
@item
@cite{The extent to which suggestions made by using the inline function
specifier are effective (C99 and C11 6.7.4).}
GCC will not inline any functions if the @option{-fno-inline} option is
used or if @option{-O0} is used. Otherwise, GCC may still be unable to
inline a function for many reasons; the @option{-Winline} option may be
used to determine if a function has not been inlined and why not.
@end itemize
@node Structures unions enumerations and bit-fields implementation
@section Structures, Unions, Enumerations, and Bit-Fields
@itemize @bullet
@item
@cite{A member of a union object is accessed using a member of a
different type (C90 6.3.2.3).}
The relevant bytes of the representation of the object are treated as
an object of the type used for the access. @xref{Type-punning}. This
may be a trap representation.
@item
@cite{Whether a ``plain'' @code{int} bit-field is treated as a
@code{signed int} bit-field or as an @code{unsigned int} bit-field
(C90 6.5.2, C90 6.5.2.1, C99 and C11 6.7.2, C99 and C11 6.7.2.1).}
@opindex funsigned-bitfields
By default it is treated as @code{signed int} but this may be changed
by the @option{-funsigned-bitfields} option.
@item
@cite{Allowable bit-field types other than @code{_Bool}, @code{signed int},
and @code{unsigned int} (C99 and C11 6.7.2.1).}
Other integer types, such as @code{long int}, and enumerated types are
permitted even in strictly conforming mode.
@item
@cite{Whether atomic types are permitted for bit-fields (C11 6.7.2.1).}
Atomic types are not permitted for bit-fields.
@item
@cite{Whether a bit-field can straddle a storage-unit boundary (C90
6.5.2.1, C99 and C11 6.7.2.1).}
Determined by ABI@.
@item
@cite{The order of allocation of bit-fields within a unit (C90
6.5.2.1, C99 and C11 6.7.2.1).}
Determined by ABI@.
@item
@cite{The alignment of non-bit-field members of structures (C90
6.5.2.1, C99 and C11 6.7.2.1).}
Determined by ABI@.
@item
@cite{The integer type compatible with each enumerated type (C90
6.5.2.2, C99 and C11 6.7.2.2).}
@opindex fshort-enums
Normally, the type is @code{unsigned int} if there are no negative
values in the enumeration, otherwise @code{int}. If
@option{-fshort-enums} is specified, then if there are negative values
it is the first of @code{signed char}, @code{short} and @code{int}
that can represent all the values, otherwise it is the first of
@code{unsigned char}, @code{unsigned short} and @code{unsigned int}
that can represent all the values.
@c On a few unusual targets with 64-bit int, this doesn't agree with
@c the code and one of the types accessed via mode attributes (which
@c are not currently considered extended integer types) may be used.
@c If these types are made extended integer types, it would still be
@c the case that -fshort-enums stops the implementation from
@c conforming to C90 on those targets.
On some targets, @option{-fshort-enums} is the default; this is
determined by the ABI@.
@end itemize
@node Qualifiers implementation
@section Qualifiers
@itemize @bullet
@item
@cite{What constitutes an access to an object that has volatile-qualified
type (C90 6.5.3, C99 and C11 6.7.3).}
Such an object is normally accessed by pointers and used for accessing
hardware. In most expressions, it is intuitively obvious what is a read
and what is a write. For example
@smallexample
volatile int *dst = @var{somevalue};
volatile int *src = @var{someothervalue};
*dst = *src;
@end smallexample
@noindent
will cause a read of the volatile object pointed to by @var{src} and store the
value into the volatile object pointed to by @var{dst}. There is no
guarantee that these reads and writes are atomic, especially for objects
larger than @code{int}.
However, if the volatile storage is not being modified, and the value of
the volatile storage is not used, then the situation is less obvious.
For example
@smallexample
volatile int *src = @var{somevalue};
*src;
@end smallexample
According to the C standard, such an expression is an rvalue whose type
is the unqualified version of its original type, i.e.@: @code{int}. Whether
GCC interprets this as a read of the volatile object being pointed to or
only as a request to evaluate the expression for its side effects depends
on this type.
If it is a scalar type, or on most targets an aggregate type whose only
member object is of a scalar type, or a union type whose member objects
are of scalar types, the expression is interpreted by GCC as a read of
the volatile object; in the other cases, the expression is only evaluated
for its side effects.
When an object of an aggregate type, with the same size and alignment as a
scalar type @code{S}, is the subject of a volatile access by an assignment
expression or an atomic function, the access to it is performed as if the
object's declared type were @code{volatile S}.
@end itemize
@node Declarators implementation
@section Declarators
@itemize @bullet
@item
@cite{The maximum number of declarators that may modify an arithmetic,
structure or union type (C90 6.5.4).}
GCC is only limited by available memory.
@end itemize
@node Statements implementation
@section Statements
@itemize @bullet
@item
@cite{The maximum number of @code{case} values in a @code{switch}
statement (C90 6.6.4.2).}
GCC is only limited by available memory.
@end itemize
@node Preprocessing directives implementation
@section Preprocessing Directives
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}, for details of these aspects of
implementation-defined behavior.
@itemize @bullet
@item
@cite{The locations within @code{#pragma} directives where header name
preprocessing tokens are recognized (C11 6.4, C11 6.4.7).}
@item
@cite{How sequences in both forms of header names are mapped to headers
or external source file names (C90 6.1.7, C99 and C11 6.4.7).}
@item
@cite{Whether the value of a character constant in a constant expression
that controls conditional inclusion matches the value of the same character
constant in the execution character set (C90 6.8.1, C99 and C11 6.10.1).}
@item
@cite{Whether the value of a single-character character constant in a
constant expression that controls conditional inclusion may have a
negative value (C90 6.8.1, C99 and C11 6.10.1).}
@item
@cite{The places that are searched for an included @samp{<>} delimited
header, and how the places are specified or the header is
identified (C90 6.8.2, C99 and C11 6.10.2).}
@item
@cite{How the named source file is searched for in an included @samp{""}
delimited header (C90 6.8.2, C99 and C11 6.10.2).}
@item
@cite{The method by which preprocessing tokens (possibly resulting from
macro expansion) in a @code{#include} directive are combined into a header
name (C90 6.8.2, C99 and C11 6.10.2).}
@item
@cite{The nesting limit for @code{#include} processing (C90 6.8.2, C99
and C11 6.10.2).}
@item
@cite{Whether the @samp{#} operator inserts a @samp{\} character before
the @samp{\} character that begins a universal character name in a
character constant or string literal (C99 and C11 6.10.3.2).}
@item
@cite{The behavior on each recognized non-@code{STDC #pragma}
directive (C90 6.8.6, C99 and C11 6.10.6).}
@xref{Pragmas, , Pragmas, cpp, The C Preprocessor}, for details of
pragmas accepted by GCC on all targets. @xref{Pragmas, , Pragmas
Accepted by GCC}, for details of target-specific pragmas.
@item
@cite{The definitions for @code{__DATE__} and @code{__TIME__} when
respectively, the date and time of translation are not available (C90
6.8.8, C99 6.10.8, C11 6.10.8.1).}
@end itemize
@node Library functions implementation
@section Library Functions
The behavior of most of these points are dependent on the implementation
of the C library, and are not defined by GCC itself.
@itemize @bullet
@item
@cite{The null pointer constant to which the macro @code{NULL} expands
(C90 7.1.6, C99 7.17, C11 7.19).}
In @code{<stddef.h>}, @code{NULL} expands to @code{((void *)0)}. GCC
does not provide the other headers which define @code{NULL} and some
library implementations may use other definitions in those headers.
@end itemize
@node Architecture implementation
@section Architecture
@itemize @bullet
@item
@cite{The values or expressions assigned to the macros specified in the
headers @code{<float.h>}, @code{<limits.h>}, and @code{<stdint.h>}
(C90, C99 and C11 5.2.4.2, C99 7.18.2, C99 7.18.3, C11 7.20.2, C11 7.20.3).}
Determined by ABI@.
@item
@cite{The result of attempting to indirectly access an object with
automatic or thread storage duration from a thread other than the one
with which it is associated (C11 6.2.4).}
Such accesses are supported, subject to the same requirements for
synchronization for concurrent accesses as for concurrent accesses to
any object.
@item
@cite{The number, order, and encoding of bytes in any object
(when not explicitly specified in this International Standard) (C99
and C11 6.2.6.1).}
Determined by ABI@.
@item
@cite{Whether any extended alignments are supported and the contexts
in which they are supported (C11 6.2.8).}
Extended alignments up to @math{2^{28}} (bytes) are supported for
objects of automatic storage duration. Alignments supported for
objects of static and thread storage duration are determined by the
ABI.
@item
@cite{Valid alignment values other than those returned by an _Alignof
expression for fundamental types, if any (C11 6.2.8).}
Valid alignments are powers of 2 up to and including @math{2^{28}}.
@item
@cite{The value of the result of the @code{sizeof} and @code{_Alignof}
operators (C90 6.3.3.4, C99 and C11 6.5.3.4).}
Determined by ABI@.
@end itemize
@node Locale-specific behavior implementation
@section Locale-Specific Behavior
The behavior of these points are dependent on the implementation
of the C library, and are not defined by GCC itself.

62
gcc/doc/implement-cxx.texi Normal file
View File

@ -0,0 +1,62 @@
@c Copyright (C) 2009-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node C++ Implementation
@chapter C++ Implementation-Defined Behavior
@cindex implementation-defined behavior, C++ language
A conforming implementation of ISO C++ is required to document its
choice of behavior in each of the areas that are designated
``implementation defined''. The following lists all such areas,
along with the section numbers from the ISO/IEC 14882:1998 and ISO/IEC
14882:2003 standards. Some areas are only implementation-defined in
one version of the standard.
Some choices depend on the externally determined ABI for the platform
(including standard character encodings) which GCC follows; these are
listed as ``determined by ABI'' below. @xref{Compatibility, , Binary
Compatibility}, and @uref{https://gcc.gnu.org/readings.html}. Some
choices are documented in the preprocessor manual.
@xref{Implementation-defined behavior, , Implementation-defined
behavior, cpp, The C Preprocessor}. Some choices are documented in
the corresponding document for the C language. @xref{C
Implementation}. Some choices are made by the library and operating
system (or other environment when compiling for a freestanding
environment); refer to their documentation for details.
@menu
* Conditionally-supported behavior::
* Exception handling::
@end menu
@node Conditionally-supported behavior
@section Conditionally-Supported Behavior
@cite{Each implementation shall include documentation that identifies
all conditionally-supported constructs that it does not support (C++0x
1.4).}
@itemize @bullet
@item
@cite{Whether an argument of class type with a non-trivial copy
constructor or destructor can be passed to ... (C++0x 5.2.2).}
Such argument passing is supported, using the same
pass-by-invisible-reference approach used for normal function
arguments of such types.
@end itemize
@node Exception handling
@section Exception Handling
@itemize @bullet
@item
@cite{In the situation where no matching handler is found, it is
implementation-defined whether or not the stack is unwound before
std::terminate() is called (C++98 15.5.1).}
The stack is not unwound before std::terminate is called.
@end itemize

547
gcc/doc/include/fdl.texi Normal file
View File

@ -0,0 +1,547 @@
@ignore
@c Set file name and title for man page.
@setfilename gfdl
@settitle GNU Free Documentation License
@c man begin SEEALSO
gpl(7), fsf-funding(7).
@c man end
@c man begin COPYRIGHT
Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
@uref{https://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@c This file is intended to be included within another document,
@c hence no sectioning command or @node.
@c man end
@end ignore
@c Special handling for inclusion in the install manual.
@ifset gfdlhtml
@ifnothtml
@comment node-name, next, previous, up
@node GNU Free Documentation License, Concept Index, Specific, Top
@end ifnothtml
@html
<h1 align="center">Installing GCC: GNU Free Documentation License</h1>
@end html
@ifnothtml
@unnumbered GNU Free Documentation License
@end ifnothtml
@end ifset
@c man begin DESCRIPTION
@ifclear gfdlhtml
@comment For some cases, this default @node/@unnumbered is not applicable and
@comment causes warnings. In those cases, the including file can set
@comment nodefaultgnufreedocumentationlicensenode and provide it's own version.
@comment F.i., when this file is included in an @raisesections context, the
@comment including file can use an @unnumberedsec.
@ifclear nodefaultgnufreedocumentationlicensenode
@node GNU Free Documentation License
@unnumbered GNU Free Documentation License
@end ifclear
@end ifclear
@cindex FDL, GNU Free Documentation License
@center Version 1.3, 3 November 2008
@display
Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
@uref{https://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display
@enumerate 0
@item
PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document @dfn{free} in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of ``copyleft'', which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
@item
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The ``Document'', below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as ``you''. You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A ``Modified Version'' of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A ``Secondary Section'' is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject. (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A ``Transparent'' copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not ``Transparent'' is called ``Opaque''.
Examples of suitable formats for Transparent copies include plain
@sc{ascii} without markup, Texinfo input format, La@TeX{} input
format, @acronym{SGML} or @acronym{XML} using a publicly available
@acronym{DTD}, and standard-conforming simple @acronym{HTML},
PostScript or @acronym{PDF} designed for human modification. Examples
of transparent image formats include @acronym{PNG}, @acronym{XCF} and
@acronym{JPG}. Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, @acronym{SGML} or
@acronym{XML} for which the @acronym{DTD} and/or processing tools are
not generally available, and the machine-generated @acronym{HTML},
PostScript or @acronym{PDF} produced by some word processors for
output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, ``Title Page'' means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
The ``publisher'' means any person or entity that distributes copies
of the Document to the public.
A section ``Entitled XYZ'' means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as ``Acknowledgements'',
``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
of such a section when you modify the Document means that it remains a
section ``Entitled XYZ'' according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
@item
VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
@item
COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
@item
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
@enumerate A
@item
Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
@item
List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
@item
State on the Title page the name of the publisher of the
Modified Version, as the publisher.
@item
Preserve all the copyright notices of the Document.
@item
Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
@item
Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
@item
Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
@item
Include an unaltered copy of this License.
@item
Preserve the section Entitled ``History'', Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
@item
Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the ``History'' section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
@item
For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
the Title of the section, and preserve in the section all the
substance and tone of each of the contributor acknowledgements and/or
dedications given therein.
@item
Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
@item
Delete any section Entitled ``Endorsements''. Such a section
may not be included in the Modified Version.
@item
Do not retitle any existing section to be Entitled ``Endorsements'' or
to conflict in title with any Invariant Section.
@item
Preserve any Warranty Disclaimers.
@end enumerate
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled ``Endorsements'', provided it contains
nothing but endorsements of your Modified Version by various
parties---for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
@item
COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled ``History''
in the various original documents, forming one section Entitled
``History''; likewise combine any sections Entitled ``Acknowledgements'',
and any sections Entitled ``Dedications''. You must delete all
sections Entitled ``Endorsements.''
@item
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
@item
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an ``aggregate'' if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
@item
TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled ``Acknowledgements'',
``Dedications'', or ``History'', the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
@item
TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, and
will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
@item
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
@uref{https://www.gnu.org/copyleft/}.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation. If the Document
specifies that a proxy can decide which future versions of this
License can be used, that proxy's public statement of acceptance of a
version permanently authorizes you to choose that version for the
Document.
@item
RELICENSING
``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server. A
``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
site means any set of copyrightable works thus published on the MMC
site.
``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
``Incorporate'' means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is ``eligible for relicensing'' if it is licensed under this
License, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole
or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
@end enumerate
@page
@unnumberedsec ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
@smallexample
@group
Copyright (C) @var{year} @var{your name}.
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 no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end group
@end smallexample
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the ``with...Texts.'' line with this:
@smallexample
@group
with the Invariant Sections being @var{list their titles}, with
the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
being @var{list}.
@end group
@end smallexample
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
@c Local Variables:
@c ispell-local-pdict: "ispell-dict"
@c End:
@c man end

60
gcc/doc/include/funding.texi Normal file
View File

@ -0,0 +1,60 @@
@ignore
@c Set file name and title for man page.
@setfilename fsf-funding
@settitle Funding Free Software
@c man begin SEEALSO
gpl(7), gfdl(7).
@c man end
@end ignore
@node Funding
@c man begin DESCRIPTION
@unnumbered Funding Free Software
If you want to have more free software a few years from now, it makes
sense for you to help encourage people to contribute funds for its
development. The most effective approach known is to encourage
commercial redistributors to donate.
Users of free software systems can boost the pace of development by
encouraging for-a-fee distributors to donate part of their selling price
to free software developers---the Free Software Foundation, and others.
The way to convince distributors to do this is to demand it and expect
it from them. So when you compare distributors, judge them partly by
how much they give to free software development. Show distributors
they must compete to be the one who gives the most.
To make this approach work, you must insist on numbers that you can
compare, such as, ``We will donate ten dollars to the Frobnitz project
for each disk sold.'' Don't be satisfied with a vague promise, such as
``A portion of the profits are donated,'' since it doesn't give a basis
for comparison.
Even a precise fraction ``of the profits from this disk'' is not very
meaningful, since creative accounting and unrelated business decisions
can greatly alter what fraction of the sales price counts as profit.
If the price you pay is $50, ten percent of the profit is probably
less than a dollar; it might be a few cents, or nothing at all.
Some redistributors do development work themselves. This is useful too;
but to keep everyone honest, you need to inquire how much they do, and
what kind. Some kinds of development make much more long-term
difference than others. For example, maintaining a separate version of
a program contributes very little; maintaining the standard version of a
program for the whole community contributes much. Easy new ports
contribute little, since someone else would surely do them; difficult
ports such as adding a new CPU to the GNU Compiler Collection contribute more;
major new features or packages contribute the most.
By establishing the idea that supporting further development is ``the
proper thing to do'' when distributing free software for a fee, we can
assure a steady flow of resources into making more free software.
@c man end
@display
@c man begin COPYRIGHT
Copyright @copyright{} 1994 Free Software Foundation, Inc.
Verbatim copying and redistribution of this section is permitted
without royalty; alteration is not permitted.
@c man end
@end display

73
gcc/doc/include/gcc-common.texi Normal file
View File

@ -0,0 +1,73 @@
@c Copyright (C) 2001-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@c Version number and development mode.
@c version-GCC is @set to the base GCC version number.
@c DEVELOPMENT is @set for an in-development version, @clear for a
@c release version (corresponding to ``experimental''/anything else
@c in gcc/DEV-PHASE).
@include gcc-vers.texi
@c Common macros to support generating man pages:
@macro gcctabopt{body}
@code{\body\}
@end macro
@macro gccoptlist{body}
@smallexample
\body\
@end smallexample
@end macro
@c Makeinfo handles the above macro OK, TeX needs manual line breaks;
@c they get lost at some point in handling the macro. But if @macro is
@c used here rather than @alias, it produces double line breaks.
@iftex
@alias gol = *
@end iftex
@ifnottex
@macro gol
@end macro
@end ifnottex
@c For FSF printing, define FSFPRINT. Also update the ISBN and last
@c printing date for the manual being printed.
@c @set FSFPRINT
@ifset FSFPRINT
@smallbook
@finalout
@c Cause even numbered pages to be printed on the left hand side of
@c the page and odd numbered pages to be printed on the right hand
@c side of the page. Using this, you can print on both sides of a
@c sheet of paper and have the text on the same part of the sheet.
@c The text on right hand pages is pushed towards the right hand
@c margin and the text on left hand pages is pushed toward the left
@c hand margin.
@c (To provide the reverse effect, set bindingoffset to -0.75in.)
@tex
\global\bindingoffset=0.75in
\global\normaloffset =0.75in
@end tex
@end ifset
@c Macro to generate a "For the N.N.N version" subtitle on the title
@c page of TeX documentation. This macro should be used in the
@c titlepage environment after the title and any other subtitles have
@c been placed, and before any authors are placed.
@macro versionsubtitle
@ifclear DEVELOPMENT
@subtitle For @sc{gcc} version @value{version-GCC}
@end ifclear
@ifset DEVELOPMENT
@subtitle For @sc{gcc} version @value{version-GCC} (pre-release)
@end ifset
@ifset VERSION_PACKAGE
@sp 1
@subtitle @value{VERSION_PACKAGE}
@end ifset
@c Even if there are no authors, the second titlepage line should be
@c forced to the bottom of the page.
@vskip 0pt plus 1filll
@end macro

733
gcc/doc/include/gpl_v3.texi Normal file
View File

@ -0,0 +1,733 @@
@ignore
@c Set file name and title for man page.
@setfilename gpl
@settitle GNU General Public License
@c man begin SEEALSO
gfdl(7), fsf-funding(7).
@c man end
@c man begin COPYRIGHT
Copyright @copyright{} 2007 Free Software Foundation, Inc.
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
@c man end
@end ignore
@node Copying
@c man begin DESCRIPTION
@unnumbered GNU General Public License
@center Version 3, 29 June 2007
@c This file is intended to be included in another file.
@display
Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{https://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
@end display
@heading Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom
to share and change all versions of a program--to make sure it remains
free software for all its users. We, the Free Software Foundation,
use the GNU General Public License for most of our software; it
applies also to any other work released this way by its authors. You
can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you
have certain responsibilities if you distribute copies of the
software, or if you modify it: responsibilities to respect the freedom
of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too,
receive or can get the source code. And you must show them these
terms so they know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the
manufacturer can do so. This is fundamentally incompatible with the
aim of protecting users' freedom to change the software. The
systematic pattern of such abuse occurs in the area of products for
individuals to use, which is precisely where it is most unacceptable.
Therefore, we have designed this version of the GPL to prohibit the
practice for those products. If such problems arise substantially in
other domains, we stand ready to extend this provision to those
domains in future versions of the GPL, as needed to protect the
freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish
to avoid the special danger that patents applied to a free program
could make it effectively proprietary. To prevent this, the GPL
assures that patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
@heading TERMS AND CONDITIONS
@enumerate 0
@item Definitions.
``This License'' refers to version 3 of the GNU General Public License.
``Copyright'' also means copyright-like laws that apply to other kinds
of works, such as semiconductor masks.
``The Program'' refers to any copyrightable work licensed under this
License. Each licensee is addressed as ``you''. ``Licensees'' and
``recipients'' may be individuals or organizations.
To ``modify'' a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of
an exact copy. The resulting work is called a ``modified version'' of
the earlier work or a work ``based on'' the earlier work.
A ``covered work'' means either the unmodified Program or a work based
on the Program.
To ``propagate'' a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To ``convey'' a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user
through a computer network, with no transfer of a copy, is not
conveying.
An interactive user interface displays ``Appropriate Legal Notices'' to
the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
@item Source Code.
The ``source code'' for a work means the preferred form of the work for
making modifications to it. ``Object code'' means any non-source form
of a work.
A ``Standard Interface'' means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The ``System Libraries'' of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
``Major Component'', in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The ``Corresponding Source'' for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users can
regenerate automatically from other parts of the Corresponding Source.
The Corresponding Source for a work in source code form is that same
work.
@item Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not convey,
without conditions so long as your license otherwise remains in force.
You may convey covered works to others for the sole purpose of having
them make modifications exclusively for you, or provide you with
facilities for running those works, provided that you comply with the
terms of this License in conveying all material for which you do not
control copyright. Those thus making or running the covered works for
you must do so exclusively on your behalf, under your direction and
control, on terms that prohibit them from making any copies of your
copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under the
conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
@item Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such
circumvention is effected by exercising rights under this License with
respect to the covered work, and you disclaim any intention to limit
operation or modification of the work as a means of enforcing, against
the work's users, your or third parties' legal rights to forbid
circumvention of technological measures.
@item Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
@item Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these
conditions:
@enumerate a
@item
The work must carry prominent notices stating that you modified it,
and giving a relevant date.
@item
The work must carry prominent notices stating that it is released
under this License and any conditions added under section 7. This
requirement modifies the requirement in section 4 to ``keep intact all
notices''.
@item
You must license the entire work, as a whole, under this License to
anyone who comes into possession of a copy. This License will
therefore apply, along with any applicable section 7 additional terms,
to the whole of the work, and all its parts, regardless of how they
are packaged. This License gives no permission to license the work in
any other way, but it does not invalidate such permission if you have
separately received it.
@item
If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your work
need not make them do so.
@end enumerate
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
``aggregate'' if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
@item Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms of
sections 4 and 5, provided that you also convey the machine-readable
Corresponding Source under the terms of this License, in one of these
ways:
@enumerate a
@item
Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium customarily
used for software interchange.
@item
Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a written
offer, valid for at least three years and valid for as long as you
offer spare parts or customer support for that product model, to give
anyone who possesses the object code either (1) a copy of the
Corresponding Source for all the software in the product that is
covered by this License, on a durable physical medium customarily used
for software interchange, for a price no more than your reasonable
cost of physically performing this conveying of source, or (2) access
to copy the Corresponding Source from a network server at no charge.
@item
Convey individual copies of the object code with a copy of the written
offer to provide the Corresponding Source. This alternative is
allowed only occasionally and noncommercially, and only if you
received the object code with such an offer, in accord with subsection
6b.
@item
Convey the object code by offering access from a designated place
(gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to copy
the object code is a network server, the Corresponding Source may be
on a different server (operated by you or a third party) that supports
equivalent copying facilities, provided you maintain clear directions
next to the object code saying where to find the Corresponding Source.
Regardless of what server hosts the Corresponding Source, you remain
obligated to ensure that it is available for as long as needed to
satisfy these requirements.
@item
Convey the object code using peer-to-peer transmission, provided you
inform other peers where the object code and Corresponding Source of
the work are being offered to the general public at no charge under
subsection 6d.
@end enumerate
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A ``User Product'' is either (1) a ``consumer product'', which means any
tangible personal property which is normally used for personal,
family, or household purposes, or (2) anything designed or sold for
incorporation into a dwelling. In determining whether a product is a
consumer product, doubtful cases shall be resolved in favor of
coverage. For a particular product received by a particular user,
``normally used'' refers to a typical or common use of that class of
product, regardless of the status of the particular user or of the way
in which the particular user actually uses, or expects or is expected
to use, the product. A product is a consumer product regardless of
whether the product has substantial commercial, industrial or
non-consumer uses, unless such uses represent the only significant
mode of use of the product.
``Installation Information'' for a User Product means any methods,
procedures, authorization keys, or other information required to
install and execute modified versions of a covered work in that User
Product from a modified version of its Corresponding Source. The
information must suffice to ensure that the continued functioning of
the modified object code is in no case prevented or interfered with
solely because modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or
updates for a work that has been modified or installed by the
recipient, or for the User Product in which it has been modified or
installed. Access to a network may be denied when the modification
itself materially and adversely affects the operation of the network
or violates the rules and protocols for communication across the
network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
@item Additional Terms.
``Additional permissions'' are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders
of that material) supplement the terms of this License with terms:
@enumerate a
@item
Disclaiming warranty or limiting liability differently from the terms
of sections 15 and 16 of this License; or
@item
Requiring preservation of specified reasonable legal notices or author
attributions in that material or in the Appropriate Legal Notices
displayed by works containing it; or
@item
Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
@item
Limiting the use for publicity purposes of names of licensors or
authors of the material; or
@item
Declining to grant rights under trademark law for use of some trade
names, trademarks, or service marks; or
@item
Requiring indemnification of licensors and authors of that material by
anyone who conveys the material (or modified versions of it) with
contractual assumptions of liability to the recipient, for any
liability that these contractual assumptions directly impose on those
licensors and authors.
@end enumerate
All other non-permissive additional terms are considered ``further
restrictions'' within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions; the
above requirements apply either way.
@item Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
@item Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or run
a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
@item Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An ``entity transaction'' is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
@item Patents.
A ``contributor'' is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's ``contributor version''.
A contributor's ``essential patent claims'' are all patent claims owned
or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, ``control'' includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a ``patent license'' is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To ``grant'' such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. ``Knowingly relying'' means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is ``discriminatory'' if it does not include within the
scope of its coverage, prohibits the exercise of, or is conditioned on
the non-exercise of one or more of the rights that are specifically
granted under this License. You may not convey a covered work if you
are a party to an arrangement with a third party that is in the
business of distributing software, under which you make payment to the
third party based on the extent of your activity of conveying the
work, and under which the third party grants, to any of the parties
who would receive the covered work from you, a discriminatory patent
license (a) in connection with copies of the covered work conveyed by
you (or copies made from those copies), or (b) primarily for and in
connection with specific products or compilations that contain the
covered work, unless you entered into that arrangement, or that patent
license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
@item No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey
a covered work so as to satisfy simultaneously your obligations under
this License and any other pertinent obligations, then as a
consequence you may not convey it at all. For example, if you agree
to terms that obligate you to collect a royalty for further conveying
from those to whom you convey the Program, the only way you could
satisfy both those terms and this License would be to refrain entirely
from conveying the Program.
@item Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
@item Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions
of the GNU General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies that a certain numbered version of the GNU General Public
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that numbered version or
of any later version published by the Free Software Foundation. If
the Program does not specify a version number of the GNU General
Public License, you may choose any version ever published by the Free
Software Foundation.
If the Program specifies that a proxy can decide which future versions
of the GNU General Public License can be used, that proxy's public
statement of acceptance of a version permanently authorizes you to
choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
@item Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.
@item Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
@item Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
@end enumerate
@heading END OF TERMS AND CONDITIONS
@heading How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.
@smallexample
@var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) @var{year} @var{name of author}
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see @url{https://www.gnu.org/licenses/}.
@end smallexample
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
@smallexample
@var{program} Copyright (C) @var{year} @var{name of author}
This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
This is free software, and you are welcome to redistribute it
under certain conditions; type @samp{show c} for details.
@end smallexample
The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License. Of course, your
program's commands might be different; for a GUI interface, you would
use an ``about box''.
You should also get your employer (if you work as a programmer) or school,
if any, to sign a ``copyright disclaimer'' for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
@url{https://www.gnu.org/licenses/}.
The GNU General Public License does not permit incorporating your
program into proprietary programs. If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library. If this is what you want to do, use
the GNU Lesser General Public License instead of this License. But
first, please read @url{https://www.gnu.org/licenses/why-not-lgpl.html}.
@c man end

5268
gcc/doc/install.texi Normal file
View File

File diff suppressed because it is too large Load Diff

70
gcc/doc/interface.texi Normal file
View File

@ -0,0 +1,70 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Interface
@chapter Interfacing to GCC Output
@cindex interfacing to GCC output
@cindex run-time conventions
@cindex function call conventions
@cindex conventions, run-time
GCC is normally configured to use the same function calling convention
normally in use on the target system. This is done with the
machine-description macros described (@pxref{Target Macros}).
@cindex unions, returning
@cindex structures, returning
@cindex returning structures and unions
However, returning of structure and union values is done differently on
some target machines. As a result, functions compiled with PCC
returning such types cannot be called from code compiled with GCC,
and vice versa. This does not cause trouble often because few Unix
library routines return structures or unions.
GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
long in the same registers used for @code{int} or @code{double} return
values. (GCC typically allocates variables of such types in
registers also.) Structures and unions of other sizes are returned by
storing them into an address passed by the caller (usually in a
register). The target hook @code{TARGET_STRUCT_VALUE_RTX}
tells GCC where to pass this address.
By contrast, PCC on most target machines returns structures and unions
of any size by copying the data into an area of static storage, and then
returning the address of that storage as if it were a pointer value.
The caller must copy the data from that memory area to the place where
the value is wanted. This is slower than the method used by GCC, and
fails to be reentrant.
On some target machines, such as RISC machines and the 80386, the
standard system convention is to pass to the subroutine the address of
where to return the value. On these machines, GCC has been
configured to be compatible with the standard compiler, when this method
is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
@cindex argument passing
@cindex passing arguments
GCC uses the system's standard convention for passing arguments. On
some machines, the first few arguments are passed in registers; in
others, all are passed on the stack. It would be possible to use
registers for argument passing on any machine, and this would probably
result in a significant speedup. But the result would be complete
incompatibility with code that follows the standard convention. So this
change is practical only if you are switching to GCC as the sole C
compiler for the system. We may implement register argument passing on
certain machines once we have a complete GNU system so that we can
compile the libraries with GCC@.
On some machines (particularly the SPARC), certain types of arguments
are passed ``by invisible reference''. This means that the value is
stored in memory, and the address of the memory location is passed to
the subroutine.
@cindex @code{longjmp} and automatic variables
If you use @code{longjmp}, beware of automatic variables. ISO C says that
automatic variables that are not declared @code{volatile} have undefined
values after a @code{longjmp}. And this is all GCC promises to do,
because it is very difficult to restore register variables correctly, and
one of GCC's features is that it can put variables in registers without
your asking it to.

35442
gcc/doc/invoke.texi Normal file
View File

File diff suppressed because it is too large Load Diff

36
gcc/doc/languages.texi Normal file
View File

@ -0,0 +1,36 @@
@c Copyright (C) 2002-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Languages
@chapter Language Front Ends in GCC
The interface to front ends for languages in GCC, and in particular
the @code{tree} structure (@pxref{GENERIC}), was initially designed for
C, and many aspects of it are still somewhat biased towards C and
C-like languages. It is, however, reasonably well suited to other
procedural languages, and front ends for many such languages have been
written for GCC@.
Writing a compiler as a front end for GCC, rather than compiling
directly to assembler or generating C code which is then compiled by
GCC, has several advantages:
@itemize @bullet
@item GCC front ends benefit from the support for many different
target machines already present in GCC@.
@item GCC front ends benefit from all the optimizations in GCC@. Some
of these, such as alias analysis, may work better when GCC is
compiling directly from source code than when it is compiling from
generated C code.
@item Better debugging information is generated when compiling
directly from source code than when going via intermediate generated C
code.
@end itemize
Because of the advantages of writing a compiler as a GCC front end,
GCC front ends have also been created for languages very different
from those for which GCC was designed, such as the declarative
logic/functional language Mercury. For these reasons, it may also be
useful to implement compilers created for specialized purposes (for
example, as part of a research project) as GCC front ends.

2304
gcc/doc/libgcc.texi Normal file
View File

File diff suppressed because it is too large Load Diff

626
gcc/doc/loop.texi Normal file
View File

@ -0,0 +1,626 @@
@c Copyright (C) 2006-2022 Free Software Foundation, Inc.
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@c ---------------------------------------------------------------------
@c Loop Representation
@c ---------------------------------------------------------------------
@node Loop Analysis and Representation
@chapter Analysis and Representation of Loops
GCC provides extensive infrastructure for work with natural loops, i.e.,
strongly connected components of CFG with only one entry block. This
chapter describes representation of loops in GCC, both on GIMPLE and in
RTL, as well as the interfaces to loop-related analyses (induction
variable analysis and number of iterations analysis).
@menu
* Loop representation:: Representation and analysis of loops.
* Loop querying:: Getting information about loops.
* Loop manipulation:: Loop manipulation functions.
* LCSSA:: Loop-closed SSA form.
* Scalar evolutions:: Induction variables on GIMPLE.
* loop-iv:: Induction variables on RTL.
* Number of iterations:: Number of iterations analysis.
* Dependency analysis:: Data dependency analysis.
@end menu
@node Loop representation
@section Loop representation
@cindex Loop representation
@cindex Loop analysis
This chapter describes the representation of loops in GCC, and functions
that can be used to build, modify and analyze this representation. Most
of the interfaces and data structures are declared in @file{cfgloop.h}.
Loop structures are analyzed and this information disposed or updated
at the discretion of individual passes. Still most of the generic
CFG manipulation routines are aware of loop structures and try to
keep them up-to-date. By this means an increasing part of the
compilation pipeline is setup to maintain loop structure across
passes to allow attaching meta information to individual loops
for consumption by later passes.
In general, a natural loop has one entry block (header) and possibly
several back edges (latches) leading to the header from the inside of
the loop. Loops with several latches may appear if several loops share
a single header, or if there is a branching in the middle of the loop.
The representation of loops in GCC however allows only loops with a
single latch. During loop analysis, headers of such loops are split and
forwarder blocks are created in order to disambiguate their structures.
Heuristic based on profile information and structure of the induction
variables in the loops is used to determine whether the latches
correspond to sub-loops or to control flow in a single loop. This means
that the analysis sometimes changes the CFG, and if you run it in the
middle of an optimization pass, you must be able to deal with the new
blocks. You may avoid CFG changes by passing
@code{LOOPS_MAY_HAVE_MULTIPLE_LATCHES} flag to the loop discovery,
note however that most other loop manipulation functions will not work
correctly for loops with multiple latch edges (the functions that only
query membership of blocks to loops and subloop relationships, or
enumerate and test loop exits, can be expected to work).
Body of the loop is the set of blocks that are dominated by its header,
and reachable from its latch against the direction of edges in CFG@. The
loops are organized in a containment hierarchy (tree) such that all the
loops immediately contained inside loop L are the children of L in the
tree. This tree is represented by the @code{struct loops} structure.
The root of this tree is a fake loop that contains all blocks in the
function. Each of the loops is represented in a @code{struct loop}
structure. Each loop is assigned an index (@code{num} field of the
@code{struct loop} structure), and the pointer to the loop is stored in
the corresponding field of the @code{larray} vector in the loops
structure. The indices do not have to be continuous, there may be
empty (@code{NULL}) entries in the @code{larray} created by deleting
loops. Also, there is no guarantee on the relative order of a loop
and its subloops in the numbering. The index of a loop never changes.
The entries of the @code{larray} field should not be accessed directly.
The function @code{get_loop} returns the loop description for a loop with
the given index. @code{number_of_loops} function returns number of loops
in the function. To traverse all loops, use a range-based for loop with
class @code{loops_list} instance. The @code{flags} argument passed to the
constructor function of class @code{loops_list} is used to determine the
direction of traversal and the set of loops visited. Each loop is
guaranteed to be visited exactly once, regardless of the changes to the
loop tree, and the loops may be removed during the traversal. The newly
created loops are never traversed, if they need to be visited, this must
be done separately after their creation.
Each basic block contains the reference to the innermost loop it belongs
to (@code{loop_father}). For this reason, it is only possible to have
one @code{struct loops} structure initialized at the same time for each
CFG@. The global variable @code{current_loops} contains the
@code{struct loops} structure. Many of the loop manipulation functions
assume that dominance information is up-to-date.
The loops are analyzed through @code{loop_optimizer_init} function. The
argument of this function is a set of flags represented in an integer
bitmask. These flags specify what other properties of the loop
structures should be calculated/enforced and preserved later:
@itemize
@item @code{LOOPS_MAY_HAVE_MULTIPLE_LATCHES}: If this flag is set, no
changes to CFG will be performed in the loop analysis, in particular,
loops with multiple latch edges will not be disambiguated. If a loop
has multiple latches, its latch block is set to NULL@. Most of
the loop manipulation functions will not work for loops in this shape.
No other flags that require CFG changes can be passed to
loop_optimizer_init.
@item @code{LOOPS_HAVE_PREHEADERS}: Forwarder blocks are created in such
a way that each loop has only one entry edge, and additionally, the
source block of this entry edge has only one successor. This creates a
natural place where the code can be moved out of the loop, and ensures
that the entry edge of the loop leads from its immediate super-loop.
@item @code{LOOPS_HAVE_SIMPLE_LATCHES}: Forwarder blocks are created to
force the latch block of each loop to have only one successor. This
ensures that the latch of the loop does not belong to any of its
sub-loops, and makes manipulation with the loops significantly easier.
Most of the loop manipulation functions assume that the loops are in
this shape. Note that with this flag, the ``normal'' loop without any
control flow inside and with one exit consists of two basic blocks.
@item @code{LOOPS_HAVE_MARKED_IRREDUCIBLE_REGIONS}: Basic blocks and
edges in the strongly connected components that are not natural loops
(have more than one entry block) are marked with
@code{BB_IRREDUCIBLE_LOOP} and @code{EDGE_IRREDUCIBLE_LOOP} flags. The
flag is not set for blocks and edges that belong to natural loops that
are in such an irreducible region (but it is set for the entry and exit
edges of such a loop, if they lead to/from this region).
@item @code{LOOPS_HAVE_RECORDED_EXITS}: The lists of exits are recorded
and updated for each loop. This makes some functions (e.g.,
@code{get_loop_exit_edges}) more efficient. Some functions (e.g.,
@code{single_exit}) can be used only if the lists of exits are
recorded.
@end itemize
These properties may also be computed/enforced later, using functions
@code{create_preheaders}, @code{force_single_succ_latches},
@code{mark_irreducible_loops} and @code{record_loop_exits}.
The properties can be queried using @code{loops_state_satisfies_p}.
The memory occupied by the loops structures should be freed with
@code{loop_optimizer_finalize} function. When loop structures are
setup to be preserved across passes this function reduces the
information to be kept up-to-date to a minimum (only
@code{LOOPS_MAY_HAVE_MULTIPLE_LATCHES} set).
The CFG manipulation functions in general do not update loop structures.
Specialized versions that additionally do so are provided for the most
common tasks. On GIMPLE, @code{cleanup_tree_cfg_loop} function can be
used to cleanup CFG while updating the loops structures if
@code{current_loops} is set.
At the moment loop structure is preserved from the start of GIMPLE
loop optimizations until the end of RTL loop optimizations. During
this time a loop can be tracked by its @code{struct loop} and number.
@node Loop querying
@section Loop querying
@cindex Loop querying
The functions to query the information about loops are declared in
@file{cfgloop.h}. Some of the information can be taken directly from
the structures. @code{loop_father} field of each basic block contains
the innermost loop to that the block belongs. The most useful fields of
loop structure (that are kept up-to-date at all times) are:
@itemize
@item @code{header}, @code{latch}: Header and latch basic blocks of the
loop.
@item @code{num_nodes}: Number of basic blocks in the loop (including
the basic blocks of the sub-loops).
@item @code{outer}, @code{inner}, @code{next}: The super-loop, the first
sub-loop, and the sibling of the loop in the loops tree.
@end itemize
There are other fields in the loop structures, many of them used only by
some of the passes, or not updated during CFG changes; in general, they
should not be accessed directly.
The most important functions to query loop structures are:
@itemize
@item @code{loop_depth}: The depth of the loop in the loops tree, i.e., the
number of super-loops of the loop.
@item @code{flow_loops_dump}: Dumps the information about loops to a
file.
@item @code{verify_loop_structure}: Checks consistency of the loop
structures.
@item @code{loop_latch_edge}: Returns the latch edge of a loop.
@item @code{loop_preheader_edge}: If loops have preheaders, returns
the preheader edge of a loop.
@item @code{flow_loop_nested_p}: Tests whether loop is a sub-loop of
another loop.
@item @code{flow_bb_inside_loop_p}: Tests whether a basic block belongs
to a loop (including its sub-loops).
@item @code{find_common_loop}: Finds the common super-loop of two loops.
@item @code{superloop_at_depth}: Returns the super-loop of a loop with
the given depth.
@item @code{tree_num_loop_insns}, @code{num_loop_insns}: Estimates the
number of insns in the loop, on GIMPLE and on RTL.
@item @code{loop_exit_edge_p}: Tests whether edge is an exit from a
loop.
@item @code{mark_loop_exit_edges}: Marks all exit edges of all loops
with @code{EDGE_LOOP_EXIT} flag.
@item @code{get_loop_body}, @code{get_loop_body_in_dom_order},
@code{get_loop_body_in_bfs_order}: Enumerates the basic blocks in the
loop in depth-first search order in reversed CFG, ordered by dominance
relation, and breath-first search order, respectively.
@item @code{single_exit}: Returns the single exit edge of the loop, or
@code{NULL} if the loop has more than one exit. You can only use this
function if @code{LOOPS_HAVE_RECORDED_EXITS} is used.
@item @code{get_loop_exit_edges}: Enumerates the exit edges of a loop.
@item @code{just_once_each_iteration_p}: Returns true if the basic block
is executed exactly once during each iteration of a loop (that is, it
does not belong to a sub-loop, and it dominates the latch of the loop).
@end itemize
@node Loop manipulation
@section Loop manipulation
@cindex Loop manipulation
The loops tree can be manipulated using the following functions:
@itemize
@item @code{flow_loop_tree_node_add}: Adds a node to the tree.
@item @code{flow_loop_tree_node_remove}: Removes a node from the tree.
@item @code{add_bb_to_loop}: Adds a basic block to a loop.
@item @code{remove_bb_from_loops}: Removes a basic block from loops.
@end itemize
Most low-level CFG functions update loops automatically. The following
functions handle some more complicated cases of CFG manipulations:
@itemize
@item @code{remove_path}: Removes an edge and all blocks it dominates.
@item @code{split_loop_exit_edge}: Splits exit edge of the loop,
ensuring that PHI node arguments remain in the loop (this ensures that
loop-closed SSA form is preserved). Only useful on GIMPLE.
@end itemize
Finally, there are some higher-level loop transformations implemented.
While some of them are written so that they should work on non-innermost
loops, they are mostly untested in that case, and at the moment, they
are only reliable for the innermost loops:
@itemize
@item @code{create_iv}: Creates a new induction variable. Only works on
GIMPLE@. @code{standard_iv_increment_position} can be used to find a
suitable place for the iv increment.
@item @code{duplicate_loop_body_to_header_edge},
@code{tree_duplicate_loop_body_to_header_edge}: These functions (on RTL and
on GIMPLE) duplicate the body of the loop prescribed number of times on
one of the edges entering loop header, thus performing either loop
unrolling or loop peeling. @code{can_duplicate_loop_p}
(@code{can_unroll_loop_p} on GIMPLE) must be true for the duplicated
loop.
@item @code{loop_version}: This function creates a copy of a loop, and
a branch before them that selects one of them depending on the
prescribed condition. This is useful for optimizations that need to
verify some assumptions in runtime (one of the copies of the loop is
usually left unchanged, while the other one is transformed in some way).
@item @code{tree_unroll_loop}: Unrolls the loop, including peeling the
extra iterations to make the number of iterations divisible by unroll
factor, updating the exit condition, and removing the exits that now
cannot be taken. Works only on GIMPLE.
@end itemize
@node LCSSA
@section Loop-closed SSA form
@cindex LCSSA
@cindex Loop-closed SSA form
Throughout the loop optimizations on tree level, one extra condition is
enforced on the SSA form: No SSA name is used outside of the loop in
that it is defined. The SSA form satisfying this condition is called
``loop-closed SSA form'' -- LCSSA@. To enforce LCSSA, PHI nodes must be
created at the exits of the loops for the SSA names that are used
outside of them. Only the real operands (not virtual SSA names) are
held in LCSSA, in order to save memory.
There are various benefits of LCSSA:
@itemize
@item Many optimizations (value range analysis, final value
replacement) are interested in the values that are defined in the loop
and used outside of it, i.e., exactly those for that we create new PHI
nodes.
@item In induction variable analysis, it is not necessary to specify the
loop in that the analysis should be performed -- the scalar evolution
analysis always returns the results with respect to the loop in that the
SSA name is defined.
@item It makes updating of SSA form during loop transformations simpler.
Without LCSSA, operations like loop unrolling may force creation of PHI
nodes arbitrarily far from the loop, while in LCSSA, the SSA form can be
updated locally. However, since we only keep real operands in LCSSA, we
cannot use this advantage (we could have local updating of real
operands, but it is not much more efficient than to use generic SSA form
updating for it as well; the amount of changes to SSA is the same).
@end itemize
However, it also means LCSSA must be updated. This is usually
straightforward, unless you create a new value in loop and use it
outside, or unless you manipulate loop exit edges (functions are
provided to make these manipulations simple).
@code{rewrite_into_loop_closed_ssa} is used to rewrite SSA form to
LCSSA, and @code{verify_loop_closed_ssa} to check that the invariant of
LCSSA is preserved.
@node Scalar evolutions
@section Scalar evolutions
@cindex Scalar evolutions
@cindex IV analysis on GIMPLE
Scalar evolutions (SCEV) are used to represent results of induction
variable analysis on GIMPLE@. They enable us to represent variables with
complicated behavior in a simple and consistent way (we only use it to
express values of polynomial induction variables, but it is possible to
extend it). The interfaces to SCEV analysis are declared in
@file{tree-scalar-evolution.h}. To use scalar evolutions analysis,
@code{scev_initialize} must be used. To stop using SCEV,
@code{scev_finalize} should be used. SCEV analysis caches results in
order to save time and memory. This cache however is made invalid by
most of the loop transformations, including removal of code. If such a
transformation is performed, @code{scev_reset} must be called to clean
the caches.
Given an SSA name, its behavior in loops can be analyzed using the
@code{analyze_scalar_evolution} function. The returned SCEV however
does not have to be fully analyzed and it may contain references to
other SSA names defined in the loop. To resolve these (potentially
recursive) references, @code{instantiate_parameters} or
@code{resolve_mixers} functions must be used.
@code{instantiate_parameters} is useful when you use the results of SCEV
only for some analysis, and when you work with whole nest of loops at
once. It will try replacing all SSA names by their SCEV in all loops,
including the super-loops of the current loop, thus providing a complete
information about the behavior of the variable in the loop nest.
@code{resolve_mixers} is useful if you work with only one loop at a
time, and if you possibly need to create code based on the value of the
induction variable. It will only resolve the SSA names defined in the
current loop, leaving the SSA names defined outside unchanged, even if
their evolution in the outer loops is known.
The SCEV is a normal tree expression, except for the fact that it may
contain several special tree nodes. One of them is
@code{SCEV_NOT_KNOWN}, used for SSA names whose value cannot be
expressed. The other one is @code{POLYNOMIAL_CHREC}. Polynomial chrec
has three arguments -- base, step and loop (both base and step may
contain further polynomial chrecs). Type of the expression and of base
and step must be the same. A variable has evolution
@code{POLYNOMIAL_CHREC(base, step, loop)} if it is (in the specified
loop) equivalent to @code{x_1} in the following example
@smallexample
while (@dots{})
@{
x_1 = phi (base, x_2);
x_2 = x_1 + step;
@}
@end smallexample
Note that this includes the language restrictions on the operations.
For example, if we compile C code and @code{x} has signed type, then the
overflow in addition would cause undefined behavior, and we may assume
that this does not happen. Hence, the value with this SCEV cannot
overflow (which restricts the number of iterations of such a loop).
In many cases, one wants to restrict the attention just to affine
induction variables. In this case, the extra expressive power of SCEV
is not useful, and may complicate the optimizations. In this case,
@code{simple_iv} function may be used to analyze a value -- the result
is a loop-invariant base and step.
@node loop-iv
@section IV analysis on RTL
@cindex IV analysis on RTL
The induction variable on RTL is simple and only allows analysis of
affine induction variables, and only in one loop at once. The interface
is declared in @file{cfgloop.h}. Before analyzing induction variables
in a loop L, @code{iv_analysis_loop_init} function must be called on L.
After the analysis (possibly calling @code{iv_analysis_loop_init} for
several loops) is finished, @code{iv_analysis_done} should be called.
The following functions can be used to access the results of the
analysis:
@itemize
@item @code{iv_analyze}: Analyzes a single register used in the given
insn. If no use of the register in this insn is found, the following
insns are scanned, so that this function can be called on the insn
returned by get_condition.
@item @code{iv_analyze_result}: Analyzes result of the assignment in the
given insn.
@item @code{iv_analyze_expr}: Analyzes a more complicated expression.
All its operands are analyzed by @code{iv_analyze}, and hence they must
be used in the specified insn or one of the following insns.
@end itemize
The description of the induction variable is provided in @code{struct
rtx_iv}. In order to handle subregs, the representation is a bit
complicated; if the value of the @code{extend} field is not
@code{UNKNOWN}, the value of the induction variable in the i-th
iteration is
@smallexample
delta + mult * extend_@{extend_mode@} (subreg_@{mode@} (base + i * step)),
@end smallexample
with the following exception: if @code{first_special} is true, then the
value in the first iteration (when @code{i} is zero) is @code{delta +
mult * base}. However, if @code{extend} is equal to @code{UNKNOWN},
then @code{first_special} must be false, @code{delta} 0, @code{mult} 1
and the value in the i-th iteration is
@smallexample
subreg_@{mode@} (base + i * step)
@end smallexample
The function @code{get_iv_value} can be used to perform these
calculations.
@node Number of iterations
@section Number of iterations analysis
@cindex Number of iterations analysis
Both on GIMPLE and on RTL, there are functions available to determine
the number of iterations of a loop, with a similar interface. The
number of iterations of a loop in GCC is defined as the number of
executions of the loop latch. In many cases, it is not possible to
determine the number of iterations unconditionally -- the determined
number is correct only if some assumptions are satisfied. The analysis
tries to verify these conditions using the information contained in the
program; if it fails, the conditions are returned together with the
result. The following information and conditions are provided by the
analysis:
@itemize
@item @code{assumptions}: If this condition is false, the rest of
the information is invalid.
@item @code{noloop_assumptions} on RTL, @code{may_be_zero} on GIMPLE: If
this condition is true, the loop exits in the first iteration.
@item @code{infinite}: If this condition is true, the loop is infinite.
This condition is only available on RTL@. On GIMPLE, conditions for
finiteness of the loop are included in @code{assumptions}.
@item @code{niter_expr} on RTL, @code{niter} on GIMPLE: The expression
that gives number of iterations. The number of iterations is defined as
the number of executions of the loop latch.
@end itemize
Both on GIMPLE and on RTL, it necessary for the induction variable
analysis framework to be initialized (SCEV on GIMPLE, loop-iv on RTL).
On GIMPLE, the results are stored to @code{struct tree_niter_desc}
structure. Number of iterations before the loop is exited through a
given exit can be determined using @code{number_of_iterations_exit}
function. On RTL, the results are returned in @code{struct niter_desc}
structure. The corresponding function is named
@code{check_simple_exit}. There are also functions that pass through
all the exits of a loop and try to find one with easy to determine
number of iterations -- @code{find_loop_niter} on GIMPLE and
@code{find_simple_exit} on RTL@. Finally, there are functions that
provide the same information, but additionally cache it, so that
repeated calls to number of iterations are not so costly --
@code{number_of_latch_executions} on GIMPLE and @code{get_simple_loop_desc}
on RTL.
Note that some of these functions may behave slightly differently than
others -- some of them return only the expression for the number of
iterations, and fail if there are some assumptions. The function
@code{number_of_latch_executions} works only for single-exit loops.
The function @code{number_of_cond_exit_executions} can be used to
determine number of executions of the exit condition of a single-exit
loop (i.e., the @code{number_of_latch_executions} increased by one).
On GIMPLE, below constraint flags affect semantics of some APIs of number
of iterations analyzer:
@itemize
@item @code{LOOP_C_INFINITE}: If this constraint flag is set, the loop
is known to be infinite. APIs like @code{number_of_iterations_exit} can
return false directly without doing any analysis.
@item @code{LOOP_C_FINITE}: If this constraint flag is set, the loop is
known to be finite, in other words, loop's number of iterations can be
computed with @code{assumptions} be true.
@end itemize
Generally, the constraint flags are set/cleared by consumers which are
loop optimizers. It's also the consumers' responsibility to set/clear
constraints correctly. Failing to do that might result in hard to track
down bugs in scev/niter consumers. One typical use case is vectorizer:
it drives number of iterations analyzer by setting @code{LOOP_C_FINITE}
and vectorizes possibly infinite loop by versioning loop with analysis
result. In return, constraints set by consumers can also help number of
iterations analyzer in following optimizers. For example, @code{niter}
of a loop versioned under @code{assumptions} is valid unconditionally.
Other constraints may be added in the future, for example, a constraint
indicating that loops' latch must roll thus @code{may_be_zero} would be
false unconditionally.
@node Dependency analysis
@section Data Dependency Analysis
@cindex Data Dependency Analysis
The code for the data dependence analysis can be found in
@file{tree-data-ref.cc} and its interface and data structures are
described in @file{tree-data-ref.h}. The function that computes the
data dependences for all the array and pointer references for a given
loop is @code{compute_data_dependences_for_loop}. This function is
currently used by the linear loop transform and the vectorization
passes. Before calling this function, one has to allocate two vectors:
a first vector will contain the set of data references that are
contained in the analyzed loop body, and the second vector will contain
the dependence relations between the data references. Thus if the
vector of data references is of size @code{n}, the vector containing the
dependence relations will contain @code{n*n} elements. However if the
analyzed loop contains side effects, such as calls that potentially can
interfere with the data references in the current analyzed loop, the
analysis stops while scanning the loop body for data references, and
inserts a single @code{chrec_dont_know} in the dependence relation
array.
The data references are discovered in a particular order during the
scanning of the loop body: the loop body is analyzed in execution order,
and the data references of each statement are pushed at the end of the
data reference array. Two data references syntactically occur in the
program in the same order as in the array of data references. This
syntactic order is important in some classical data dependence tests,
and mapping this order to the elements of this array avoids costly
queries to the loop body representation.
Three types of data references are currently handled: ARRAY_REF,
INDIRECT_REF and COMPONENT_REF@. The data structure for the data reference
is @code{data_reference}, where @code{data_reference_p} is a name of a
pointer to the data reference structure. The structure contains the
following elements:
@itemize
@item @code{base_object_info}: Provides information about the base object
of the data reference and its access functions. These access functions
represent the evolution of the data reference in the loop relative to
its base, in keeping with the classical meaning of the data reference
access function for the support of arrays. For example, for a reference
@code{a.b[i][j]}, the base object is @code{a.b} and the access functions,
one for each array subscript, are:
@code{@{i_init, + i_step@}_1, @{j_init, +, j_step@}_2}.
@item @code{first_location_in_loop}: Provides information about the first
location accessed by the data reference in the loop and about the access
function used to represent evolution relative to this location. This data
is used to support pointers, and is not used for arrays (for which we
have base objects). Pointer accesses are represented as a one-dimensional
access that starts from the first location accessed in the loop. For
example:
@smallexample
for1 i
for2 j
*((int *)p + i + j) = a[i][j];
@end smallexample
The access function of the pointer access is @code{@{0, + 4B@}_for2}
relative to @code{p + i}. The access functions of the array are
@code{@{i_init, + i_step@}_for1} and @code{@{j_init, +, j_step@}_for2}
relative to @code{a}.
Usually, the object the pointer refers to is either unknown, or we cannot
prove that the access is confined to the boundaries of a certain object.
Two data references can be compared only if at least one of these two
representations has all its fields filled for both data references.
The current strategy for data dependence tests is as follows:
If both @code{a} and @code{b} are represented as arrays, compare
@code{a.base_object} and @code{b.base_object};
if they are equal, apply dependence tests (use access functions based on
base_objects).
Else if both @code{a} and @code{b} are represented as pointers, compare
@code{a.first_location} and @code{b.first_location};
if they are equal, apply dependence tests (use access functions based on
first location).
However, if @code{a} and @code{b} are represented differently, only try
to prove that the bases are definitely different.
@item Aliasing information.
@item Alignment information.
@end itemize
The structure describing the relation between two data references is
@code{data_dependence_relation} and the shorter name for a pointer to
such a structure is @code{ddr_p}. This structure contains:
@itemize
@item a pointer to each data reference,
@item a tree node @code{are_dependent} that is set to @code{chrec_known}
if the analysis has proved that there is no dependence between these two
data references, @code{chrec_dont_know} if the analysis was not able to
determine any useful result and potentially there could exist a
dependence between these data references, and @code{are_dependent} is
set to @code{NULL_TREE} if there exist a dependence relation between the
data references, and the description of this dependence relation is
given in the @code{subscripts}, @code{dir_vects}, and @code{dist_vects}
arrays,
@item a boolean that determines whether the dependence relation can be
represented by a classical distance vector,
@item an array @code{subscripts} that contains a description of each
subscript of the data references. Given two array accesses a
subscript is the tuple composed of the access functions for a given
dimension. For example, given @code{A[f1][f2][f3]} and
@code{B[g1][g2][g3]}, there are three subscripts: @code{(f1, g1), (f2,
g2), (f3, g3)}.
@item two arrays @code{dir_vects} and @code{dist_vects} that contain
classical representations of the data dependences under the form of
direction and distance dependence vectors,
@item an array of loops @code{loop_nest} that contains the loops to
which the distance and direction vectors refer to.
@end itemize
Several functions for pretty printing the information extracted by the
data dependence analysis are available: @code{dump_ddrs} prints with a
maximum verbosity the details of a data dependence relations array,
@code{dump_dist_dir_vectors} prints only the classical distance and
direction vectors for a data dependence relations array, and
@code{dump_data_references} prints the details of the data references
contained in a data reference array.

131
gcc/doc/lto-dump.texi Normal file
View File

@ -0,0 +1,131 @@
@c Copyright (C) 2018-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@ignore
@c man begin COPYRIGHT
Copyright @copyright{} 2017-2022 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 ``GNU General Public License'' and ``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 gfdl(7) man page.
(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.
@c man end
@c Set file name and title for the man page.
@setfilename lto-dump
@settitle Tool for dumping LTO object files.
@end ignore
@node lto-dump
@chapter @command{lto-dump}---Tool for dumping LTO object files.
@menu
* lto-dump Intro:: Introduction to lto-dump.
* Invoking lto-dump:: How to use lto-dump.
@end menu
@node lto-dump Intro
@section Introduction to @command{lto-dump}
@c man begin DESCRIPTION
@command{lto-dump} is a tool you can use in conjunction with GCC to
dump link time optimization object files.
@c man end
@node Invoking lto-dump
@section Invoking @command{lto-dump}
@smallexample
Usage: lto-dump @r{[}@var{OPTION}@r{]} ... @var{objfiles}
@end smallexample
@command{lto-dump} accepts the following options:
@ignore
@c man begin SYNOPSIS
lto-dump [@option{-list}]
[@option{-demangle}]
[@option{-defined-only}]
[@option{-print-value}]
[@option{-name-sort}]
[@option{-size-sort}]
[@option{-reverse-sort}]
[@option{-no-sort}]
[@option{-symbol=}]
[@option{-objects}]
[@option{-type-stats}]
[@option{-tree-stats}]
[@option{-gimple-stats}]
[@option{-dump-level=}]
[@option{-dump-body=}]
[@option{-help}] @var{lto-dump}
@c man end
@end ignore
@c man begin OPTIONS
@table @gcctabopt
@item -list
Dumps list of details of functions and variables.
@item -demangle
Dump the demangled output.
@item -defined-only
Dump only the defined symbols.
@item -print-value
Dump initial values of the variables.
@item -name-sort
Sort the symbols alphabetically.
@item -size-sort
Sort the symbols according to size.
@item -reverse-sort
Dump the symbols in reverse order.
@item -no-sort
Dump the symbols in order of occurrence.
@item -symbol=
Dump the details of specific symbol.
@item -objects
Dump the details of LTO objects.
@item -type-stats
Dump the statistics of tree types.
@item -tree-stats
Dump the statistics of trees.
@item -gimple-stats
Dump the statistics of gimple statements.
@item -dump-level=
For deciding the optimization level of body.
@item -dump-body=
Dump the specific gimple body.
@item -help
Display the dump tool help.
@end table
@c man end

591
gcc/doc/lto.texi Normal file
View File

@ -0,0 +1,591 @@
@c Copyright (C) 2010-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@c Contributed by Jan Hubicka <jh@suse.cz> and
@c Diego Novillo <dnovillo@google.com>
@node LTO
@chapter Link Time Optimization
@cindex lto
@cindex whopr
@cindex wpa
@cindex ltrans
Link Time Optimization (LTO) gives GCC the capability of
dumping its internal representation (GIMPLE) to disk,
so that all the different compilation units that make up
a single executable can be optimized as a single module.
This expands the scope of inter-procedural optimizations
to encompass the whole program (or, rather, everything
that is visible at link time).
@menu
* LTO Overview:: Overview of LTO.
* LTO object file layout:: LTO file sections in ELF.
* IPA:: Using summary information in IPA passes.
* WHOPR:: Whole program assumptions,
linker plugin and symbol visibilities.
* Internal flags:: Internal flags controlling @code{lto1}.
@end menu
@node LTO Overview
@section Design Overview
Link time optimization is implemented as a GCC front end for a
bytecode representation of GIMPLE that is emitted in special sections
of @code{.o} files. Currently, LTO support is enabled in most
ELF-based systems, as well as darwin, cygwin and mingw systems.
By default, object files generated with LTO support contain only GIMPLE
bytecode. Such objects are called ``slim'', and they require that
tools like @code{ar} and @code{nm} understand symbol tables of LTO
sections. For most targets these tools have been extended to use the
plugin infrastructure, so GCC can support ``slim'' objects consisting
of the intermediate code alone.
GIMPLE bytecode could also be saved alongside final object code if
the @option{-ffat-lto-objects} option is passed, or if no plugin support
is detected for @code{ar} and @code{nm} when GCC is configured. It makes
the object files generated with LTO support larger than regular object
files. This ``fat'' object format allows to ship one set of fat
objects which could be used both for development and the production of
optimized builds. A, perhaps surprising, side effect of this feature
is that any mistake in the toolchain leads to LTO information not
being used (e.g.@: an older @code{libtool} calling @code{ld} directly).
This is both an advantage, as the system is more robust, and a
disadvantage, as the user is not informed that the optimization has
been disabled.
At the highest level, LTO splits the compiler in two. The first half
(the ``writer'') produces a streaming representation of all the
internal data structures needed to optimize and generate code. This
includes declarations, types, the callgraph and the GIMPLE representation
of function bodies.
When @option{-flto} is given during compilation of a source file, the
pass manager executes all the passes in @code{all_lto_gen_passes}.
Currently, this phase is composed of two IPA passes:
@itemize @bullet
@item @code{pass_ipa_lto_gimple_out}
This pass executes the function @code{lto_output} in
@file{lto-streamer-out.cc}, which traverses the call graph encoding
every reachable declaration, type and function. This generates a
memory representation of all the file sections described below.
@item @code{pass_ipa_lto_finish_out}
This pass executes the function @code{produce_asm_for_decls} in
@file{lto-streamer-out.cc}, which takes the memory image built in the
previous pass and encodes it in the corresponding ELF file sections.
@end itemize
The second half of LTO support is the ``reader''. This is implemented
as the GCC front end @file{lto1} in @file{lto/lto.cc}. When
@file{collect2} detects a link set of @code{.o}/@code{.a} files with
LTO information and the @option{-flto} is enabled, it invokes
@file{lto1} which reads the set of files and aggregates them into a
single translation unit for optimization. The main entry point for
the reader is @file{lto/lto.cc}:@code{lto_main}.
@subsection LTO modes of operation
One of the main goals of the GCC link-time infrastructure was to allow
effective compilation of large programs. For this reason GCC implements two
link-time compilation modes.
@enumerate
@item @emph{LTO mode}, in which the whole program is read into the
compiler at link-time and optimized in a similar way as if it
were a single source-level compilation unit.
@item @emph{WHOPR or partitioned mode}, designed to utilize multiple
CPUs and/or a distributed compilation environment to quickly link
large applications. WHOPR stands for WHOle Program optimizeR (not to
be confused with the semantics of @option{-fwhole-program}). It
partitions the aggregated callgraph from many different @code{.o}
files and distributes the compilation of the sub-graphs to different
CPUs.
Note that distributed compilation is not implemented yet, but since
the parallelism is facilitated via generating a @code{Makefile}, it
would be easy to implement.
@end enumerate
WHOPR splits LTO into three main stages:
@enumerate
@item Local generation (LGEN)
This stage executes in parallel. Every file in the program is compiled
into the intermediate language and packaged together with the local
call-graph and summary information. This stage is the same for both
the LTO and WHOPR compilation mode.
@item Whole Program Analysis (WPA)
WPA is performed sequentially. The global call-graph is generated, and
a global analysis procedure makes transformation decisions. The global
call-graph is partitioned to facilitate parallel optimization during
phase 3. The results of the WPA stage are stored into new object files
which contain the partitions of program expressed in the intermediate
language and the optimization decisions.
@item Local transformations (LTRANS)
This stage executes in parallel. All the decisions made during phase 2
are implemented locally in each partitioned object file, and the final
object code is generated. Optimizations which cannot be decided
efficiently during the phase 2 may be performed on the local
call-graph partitions.
@end enumerate
WHOPR can be seen as an extension of the usual LTO mode of
compilation. In LTO, WPA and LTRANS are executed within a single
execution of the compiler, after the whole program has been read into
memory.
When compiling in WHOPR mode, the callgraph is partitioned during
the WPA stage. The whole program is split into a given number of
partitions of roughly the same size. The compiler tries to
minimize the number of references which cross partition boundaries.
The main advantage of WHOPR is to allow the parallel execution of
LTRANS stages, which are the most time-consuming part of the
compilation process. Additionally, it avoids the need to load the
whole program into memory.
@node LTO object file layout
@section LTO file sections
LTO information is stored in several ELF sections inside object files.
Data structures and enum codes for sections are defined in
@file{lto-streamer.h}.
These sections are emitted from @file{lto-streamer-out.cc} and mapped
in all at once from @file{lto/lto.cc}:@code{lto_file_read}. The
individual functions dealing with the reading/writing of each section
are described below.
@itemize @bullet
@item Command line options (@code{.gnu.lto_.opts})
This section contains the command line options used to generate the
object files. This is used at link time to determine the optimization
level and other settings when they are not explicitly specified at the
linker command line.
Currently, GCC does not support combining LTO object files compiled
with different set of the command line options into a single binary.
At link time, the options given on the command line and the options
saved on all the files in a link-time set are applied globally. No
attempt is made at validating the combination of flags (other than the
usual validation done by option processing). This is implemented in
@file{lto/lto.cc}:@code{lto_read_all_file_options}.
@item Symbol table (@code{.gnu.lto_.symtab})
This table replaces the ELF symbol table for functions and variables
represented in the LTO IL. Symbols used and exported by the optimized
assembly code of ``fat'' objects might not match the ones used and
exported by the intermediate code. This table is necessary because
the intermediate code is less optimized and thus requires a separate
symbol table.
Additionally, the binary code in the ``fat'' object will lack a call
to a function, since the call was optimized out at compilation time
after the intermediate language was streamed out. In some special
cases, the same optimization may not happen during link-time
optimization. This would lead to an undefined symbol if only one
symbol table was used.
The symbol table is emitted in
@file{lto-streamer-out.cc}:@code{produce_symtab}.
@item Global declarations and types (@code{.gnu.lto_.decls})
This section contains an intermediate language dump of all
declarations and types required to represent the callgraph, static
variables and top-level debug info.
The contents of this section are emitted in
@file{lto-streamer-out.cc}:@code{produce_asm_for_decls}. Types and
symbols are emitted in a topological order that preserves the sharing
of pointers when the file is read back in
(@file{lto.cc}:@code{read_cgraph_and_symbols}).
@item The callgraph (@code{.gnu.lto_.cgraph})
This section contains the basic data structure used by the GCC
inter-procedural optimization infrastructure. This section stores an
annotated multi-graph which represents the functions and call sites as
well as the variables, aliases and top-level @code{asm} statements.
This section is emitted in
@file{lto-streamer-out.cc}:@code{output_cgraph} and read in
@file{lto-cgraph.cc}:@code{input_cgraph}.
@item IPA references (@code{.gnu.lto_.refs})
This section contains references between function and static
variables. It is emitted by @file{lto-cgraph.cc}:@code{output_refs}
and read by @file{lto-cgraph.cc}:@code{input_refs}.
@item Function bodies (@code{.gnu.lto_.function_body.<name>})
This section contains function bodies in the intermediate language
representation. Every function body is in a separate section to allow
copying of the section independently to different object files or
reading the function on demand.
Functions are emitted in
@file{lto-streamer-out.cc}:@code{output_function} and read in
@file{lto-streamer-in.cc}:@code{input_function}.
@item Static variable initializers (@code{.gnu.lto_.vars})
This section contains all the symbols in the global variable pool. It
is emitted by @file{lto-cgraph.cc}:@code{output_varpool} and read in
@file{lto-cgraph.cc}:@code{input_cgraph}.
@item Summaries and optimization summaries used by IPA passes
(@code{.gnu.lto_.<xxx>}, where @code{<xxx>} is one of @code{jmpfuncs},
@code{pureconst} or @code{reference})
These sections are used by IPA passes that need to emit summary
information during LTO generation to be read and aggregated at
link time. Each pass is responsible for implementing two pass manager
hooks: one for writing the summary and another for reading it in. The
format of these sections is entirely up to each individual pass. The
only requirement is that the writer and reader hooks agree on the
format.
@end itemize
@node IPA
@section Using summary information in IPA passes
Programs are represented internally as a @emph{callgraph} (a
multi-graph where nodes are functions and edges are call sites)
and a @emph{varpool} (a list of static and external variables in
the program).
The inter-procedural optimization is organized as a sequence of
individual passes, which operate on the callgraph and the
varpool. To make the implementation of WHOPR possible, every
inter-procedural optimization pass is split into several stages
that are executed at different times during WHOPR compilation:
@itemize @bullet
@item LGEN time
@enumerate
@item @emph{Generate summary} (@code{generate_summary} in
@code{struct ipa_opt_pass_d}). This stage analyzes every function
body and variable initializer is examined and stores relevant
information into a pass-specific data structure.
@item @emph{Write summary} (@code{write_summary} in
@code{struct ipa_opt_pass_d}). This stage writes all the
pass-specific information generated by @code{generate_summary}.
Summaries go into their own @code{LTO_section_*} sections that
have to be declared in @file{lto-streamer.h}:@code{enum
lto_section_type}. A new section is created by calling
@code{create_output_block} and data can be written using the
@code{lto_output_*} routines.
@end enumerate
@item WPA time
@enumerate
@item @emph{Read summary} (@code{read_summary} in
@code{struct ipa_opt_pass_d}). This stage reads all the
pass-specific information in exactly the same order that it was
written by @code{write_summary}.
@item @emph{Execute} (@code{execute} in @code{struct
opt_pass}). This performs inter-procedural propagation. This
must be done without actual access to the individual function
bodies or variable initializers. Typically, this results in a
transitive closure operation over the summary information of all
the nodes in the callgraph.
@item @emph{Write optimization summary}
(@code{write_optimization_summary} in @code{struct
ipa_opt_pass_d}). This writes the result of the inter-procedural
propagation into the object file. This can use the same data
structures and helper routines used in @code{write_summary}.
@end enumerate
@item LTRANS time
@enumerate
@item @emph{Read optimization summary}
(@code{read_optimization_summary} in @code{struct
ipa_opt_pass_d}). The counterpart to
@code{write_optimization_summary}. This reads the interprocedural
optimization decisions in exactly the same format emitted by
@code{write_optimization_summary}.
@item @emph{Transform} (@code{function_transform} and
@code{variable_transform} in @code{struct ipa_opt_pass_d}).
The actual function bodies and variable initializers are updated
based on the information passed down from the @emph{Execute} stage.
@end enumerate
@end itemize
The implementation of the inter-procedural passes are shared
between LTO, WHOPR and classic non-LTO compilation.
@itemize
@item During the traditional file-by-file mode every pass executes its
own @emph{Generate summary}, @emph{Execute}, and @emph{Transform}
stages within the single execution context of the compiler.
@item In LTO compilation mode, every pass uses @emph{Generate
summary} and @emph{Write summary} stages at compilation time,
while the @emph{Read summary}, @emph{Execute}, and
@emph{Transform} stages are executed at link time.
@item In WHOPR mode all stages are used.
@end itemize
To simplify development, the GCC pass manager differentiates
between normal inter-procedural passes (@pxref{Regular IPA passes}),
small inter-procedural passes (@pxref{Small IPA passes})
and late inter-procedural passes (@pxref{Late IPA passes}).
A small or late IPA pass (@code{SIMPLE_IPA_PASS}) does
everything at once and thus cannot be executed during WPA in
WHOPR mode. It defines only the @emph{Execute} stage and during
this stage it accesses and modifies the function bodies. Such
passes are useful for optimization at LGEN or LTRANS time and are
used, for example, to implement early optimization before writing
object files. The simple inter-procedural passes can also be used
for easier prototyping and development of a new inter-procedural
pass.
@subsection Virtual clones
One of the main challenges of introducing the WHOPR compilation
mode was addressing the interactions between optimization passes.
In LTO compilation mode, the passes are executed in a sequence,
each of which consists of analysis (or @emph{Generate summary}),
propagation (or @emph{Execute}) and @emph{Transform} stages.
Once the work of one pass is finished, the next pass sees the
updated program representation and can execute. This makes the
individual passes dependent on each other.
In WHOPR mode all passes first execute their @emph{Generate
summary} stage. Then summary writing marks the end of the LGEN
stage. At WPA time,
the summaries are read back into memory and all passes run the
@emph{Execute} stage. Optimization summaries are streamed and
sent to LTRANS, where all the passes execute the @emph{Transform}
stage.
Most optimization passes split naturally into analysis,
propagation and transformation stages. But some do not. The
main problem arises when one pass performs changes and the
following pass gets confused by seeing different callgraphs
between the @emph{Transform} stage and the @emph{Generate summary}
or @emph{Execute} stage. This means that the passes are required
to communicate their decisions with each other.
To facilitate this communication, the GCC callgraph
infrastructure implements @emph{virtual clones}, a method of
representing the changes performed by the optimization passes in
the callgraph without needing to update function bodies.
A @emph{virtual clone} in the callgraph is a function that has no
associated body, just a description of how to create its body based
on a different function (which itself may be a virtual clone).
The description of function modifications includes adjustments to
the function's signature (which allows, for example, removing or
adding function arguments), substitutions to perform on the
function body, and, for inlined functions, a pointer to the
function that it will be inlined into.
It is also possible to redirect any edge of the callgraph from a
function to its virtual clone. This implies updating of the call
site to adjust for the new function signature.
Most of the transformations performed by inter-procedural
optimizations can be represented via virtual clones. For
instance, a constant propagation pass can produce a virtual clone
of the function which replaces one of its arguments by a
constant. The inliner can represent its decisions by producing a
clone of a function whose body will be later integrated into
a given function.
Using @emph{virtual clones}, the program can be easily updated
during the @emph{Execute} stage, solving most of pass interactions
problems that would otherwise occur during @emph{Transform}.
Virtual clones are later materialized in the LTRANS stage and
turned into real functions. Passes executed after the virtual
clone were introduced also perform their @emph{Transform} stage
on new functions, so for a pass there is no significant
difference between operating on a real function or a virtual
clone introduced before its @emph{Execute} stage.
Optimization passes then work on virtual clones introduced before
their @emph{Execute} stage as if they were real functions. The
only difference is that clones are not visible during the
@emph{Generate Summary} stage.
To keep function summaries updated, the callgraph interface
allows an optimizer to register a callback that is called every
time a new clone is introduced as well as when the actual
function or variable is generated or when a function or variable
is removed. These hooks are registered in the @emph{Generate
summary} stage and allow the pass to keep its information intact
until the @emph{Execute} stage. The same hooks can also be
registered during the @emph{Execute} stage to keep the
optimization summaries updated for the @emph{Transform} stage.
@subsection IPA references
GCC represents IPA references in the callgraph. For a function
or variable @code{A}, the @emph{IPA reference} is a list of all
locations where the address of @code{A} is taken and, when
@code{A} is a variable, a list of all direct stores and reads
to/from @code{A}. References represent an oriented multi-graph on
the union of nodes of the callgraph and the varpool. See
@file{ipa-reference.cc}:@code{ipa_reference_write_optimization_summary}
and
@file{ipa-reference.cc}:@code{ipa_reference_read_optimization_summary}
for details.
@subsection Jump functions
Suppose that an optimization pass sees a function @code{A} and it
knows the values of (some of) its arguments. The @emph{jump
function} describes the value of a parameter of a given function
call in function @code{A} based on this knowledge.
Jump functions are used by several optimizations, such as the
inter-procedural constant propagation pass and the
devirtualization pass. The inliner also uses jump functions to
perform inlining of callbacks.
@node WHOPR
@section Whole program assumptions, linker plugin and symbol visibilities
Link-time optimization gives relatively minor benefits when used
alone. The problem is that propagation of inter-procedural
information does not work well across functions and variables
that are called or referenced by other compilation units (such as
from a dynamically linked library). We say that such functions
and variables are @emph{externally visible}.
To make the situation even more difficult, many applications
organize themselves as a set of shared libraries, and the default
ELF visibility rules allow one to overwrite any externally
visible symbol with a different symbol at runtime. This
basically disables any optimizations across such functions and
variables, because the compiler cannot be sure that the function
body it is seeing is the same function body that will be used at
runtime. Any function or variable not declared @code{static} in
the sources degrades the quality of inter-procedural
optimization.
To avoid this problem the compiler must assume that it sees the
whole program when doing link-time optimization. Strictly
speaking, the whole program is rarely visible even at link-time.
Standard system libraries are usually linked dynamically or not
provided with the link-time information. In GCC, the whole
program option (@option{-fwhole-program}) asserts that every
function and variable defined in the current compilation
unit is static, except for function @code{main} (note: at
link time, the current unit is the union of all objects compiled
with LTO). Since some functions and variables need to
be referenced externally, for example by another DSO or from an
assembler file, GCC also provides the function and variable
attribute @code{externally_visible} which can be used to disable
the effect of @option{-fwhole-program} on a specific symbol.
The whole program mode assumptions are slightly more complex in
C++, where inline functions in headers are put into @emph{COMDAT}
sections. COMDAT function and variables can be defined by
multiple object files and their bodies are unified at link-time
and dynamic link-time. COMDAT functions are changed to local only
when their address is not taken and thus un-sharing them with a
library is not harmful. COMDAT variables always remain externally
visible, however for readonly variables it is assumed that their
initializers cannot be overwritten by a different value.
GCC provides the function and variable attribute
@code{visibility} that can be used to specify the visibility of
externally visible symbols (or alternatively an
@option{-fdefault-visibility} command line option). ELF defines
the @code{default}, @code{protected}, @code{hidden} and
@code{internal} visibilities.
The most commonly used is visibility is @code{hidden}. It
specifies that the symbol cannot be referenced from outside of
the current shared library. Unfortunately, this information
cannot be used directly by the link-time optimization in the
compiler since the whole shared library also might contain
non-LTO objects and those are not visible to the compiler.
GCC solves this problem using linker plugins. A @emph{linker
plugin} is an interface to the linker that allows an external
program to claim the ownership of a given object file. The linker
then performs the linking procedure by querying the plugin about
the symbol table of the claimed objects and once the linking
decisions are complete, the plugin is allowed to provide the
final object file before the actual linking is made. The linker
plugin obtains the symbol resolution information which specifies
which symbols provided by the claimed objects are bound from the
rest of a binary being linked.
GCC is designed to be independent of the rest of the toolchain
and aims to support linkers without plugin support. For this
reason it does not use the linker plugin by default. Instead,
the object files are examined by @command{collect2} before being
passed to the linker and objects found to have LTO sections are
passed to @command{lto1} first. This mode does not work for
library archives. The decision on what object files from the
archive are needed depends on the actual linking and thus GCC
would have to implement the linker itself. The resolution
information is missing too and thus GCC needs to make an educated
guess based on @option{-fwhole-program}. Without the linker
plugin GCC also assumes that symbols are declared @code{hidden}
and not referred by non-LTO code by default.
@node Internal flags
@section Internal flags controlling @code{lto1}
The following flags are passed into @command{lto1} and are not
meant to be used directly from the command line.
@itemize
@item -fwpa
@opindex fwpa
This option runs the serial part of the link-time optimizer
performing the inter-procedural propagation (WPA mode). The
compiler reads in summary information from all inputs and
performs an analysis based on summary information only. It
generates object files for subsequent runs of the link-time
optimizer where individual object files are optimized using both
summary information from the WPA mode and the actual function
bodies. It then drives the LTRANS phase.
@item -fltrans
@opindex fltrans
This option runs the link-time optimizer in the
local-transformation (LTRANS) mode, which reads in output from a
previous run of the LTO in WPA mode. In the LTRANS mode, LTO
optimizes an object and produces the final assembly.
@item -fltrans-output-list=@var{file}
@opindex fltrans-output-list
This option specifies a file to which the names of LTRANS output
files are written. This option is only meaningful in conjunction
with @option{-fwpa}.
@item -fresolution=@var{file}
@opindex fresolution
This option specifies the linker resolution file. This option is
only meaningful in conjunction with @option{-fwpa} and as option
to pass through to the LTO linker plugin.
@end itemize

201
gcc/doc/makefile.texi Normal file
View File

@ -0,0 +1,201 @@
@c Copyright (C) 2001-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Makefile
@subsection Makefile Targets
@cindex makefile targets
@cindex targets, makefile
These targets are available from the @samp{gcc} directory:
@table @code
@item all
This is the default target. Depending on what your build/host/target
configuration is, it coordinates all the things that need to be built.
@item doc
Produce info-formatted documentation and man pages. Essentially it
calls @samp{make man} and @samp{make info}.
@item dvi
Produce DVI-formatted documentation.
@item pdf
Produce PDF-formatted documentation.
@item html
Produce HTML-formatted documentation.
@item man
Generate man pages.
@item info
Generate info-formatted pages.
@item mostlyclean
Delete the files made while building the compiler.
@item clean
That, and all the other files built by @samp{make all}.
@item distclean
That, and all the files created by @command{configure}.
@item maintainer-clean
Distclean plus any file that can be generated from other files. Note
that additional tools may be required beyond what is normally needed to
build GCC.
@item srcextra
Generates files in the source directory that are not version-controlled but
should go into a release tarball.
@item srcinfo
@itemx srcman
Copies the info-formatted and manpage documentation into the source
directory usually for the purpose of generating a release tarball.
@item install
Installs GCC.
@item uninstall
Deletes installed files, though this is not supported.
@item check
Run the testsuite. This creates a @file{testsuite} subdirectory that
has various @file{.sum} and @file{.log} files containing the results of
the testing. You can run subsets with, for example, @samp{make check-gcc}.
You can specify specific tests by setting @env{RUNTESTFLAGS} to be the name
of the @file{.exp} file, optionally followed by (for some tests) an equals
and a file wildcard, like:
@smallexample
make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
@end smallexample
Note that running the testsuite may require additional tools be
installed, such as Tcl or DejaGnu.
@end table
The toplevel tree from which you start GCC compilation is not
the GCC directory, but rather a complex Makefile that coordinates
the various steps of the build, including bootstrapping the compiler
and using the new compiler to build target libraries.
When GCC is configured for a native configuration, the default action
for @command{make} is to do a full three-stage bootstrap. This means
that GCC is built three times---once with the native compiler, once with
the native-built compiler it just built, and once with the compiler it
built the second time. In theory, the last two should produce the same
results, which @samp{make compare} can check. Each stage is configured
separately and compiled into a separate directory, to minimize problems
due to ABI incompatibilities between the native compiler and GCC.
If you do a change, rebuilding will also start from the first stage
and ``bubble'' up the change through the three stages. Each stage
is taken from its build directory (if it had been built previously),
rebuilt, and copied to its subdirectory. This will allow you to, for
example, continue a bootstrap after fixing a bug which causes the
stage2 build to crash. It does not provide as good coverage of the
compiler as bootstrapping from scratch, but it ensures that the new
code is syntactically correct (e.g., that you did not use GCC extensions
by mistake), and avoids spurious bootstrap comparison
failures@footnote{Except if the compiler was buggy and miscompiled
some of the files that were not modified. In this case, it's best
to use @command{make restrap}.}.
Other targets available from the top level include:
@table @code
@item bootstrap-lean
Like @code{bootstrap}, except that the various stages are removed once
they're no longer needed. This saves disk space.
@item bootstrap2
@itemx bootstrap2-lean
Performs only the first two stages of bootstrap. Unlike a three-stage
bootstrap, this does not perform a comparison to test that the compiler
is running properly. Note that the disk space required by a ``lean''
bootstrap is approximately independent of the number of stages.
@item stage@var{N}-bubble (@var{N} = 1@dots{}4, profile, feedback)
Rebuild all the stages up to @var{N}, with the appropriate flags,
``bubbling'' the changes as described above.
@item all-stage@var{N} (@var{N} = 1@dots{}4, profile, feedback)
Assuming that stage @var{N} has already been built, rebuild it with the
appropriate flags. This is rarely needed.
@item cleanstrap
Remove everything (@samp{make clean}) and rebuilds (@samp{make bootstrap}).
@item compare
Compares the results of stages 2 and 3. This ensures that the compiler
is running properly, since it should produce the same object files
regardless of how it itself was compiled.
@item distclean-stage@var{N} (@var{N} = 1@dots{}4, profile, feedback)
Wipe stage @var{N} and all the following ones.
For example,
@samp{make distclean-stage3} wipes stage 3 and all the following ones,
so that another @command{make} then rebuilds them from scratch.
This can be useful if you're doing changes where
``bubbling'' the changes as described above is not sufficient,
but a full @command{make restrap} isn't necessary either.
@item profiledbootstrap
Builds a compiler with profiling feedback information. In this case,
the second and third stages are named @samp{profile} and @samp{feedback},
respectively. For more information, see the installation instructions.
@item restrap
Restart a bootstrap, so that everything that was not built with
the system compiler is rebuilt.
@item stage@var{N}-start (@var{N} = 1@dots{}4, profile, feedback)
For each package that is bootstrapped, rename directories so that,
for example, @file{gcc} points to the stage@var{N} GCC, compiled
with the stage@var{N-1} GCC@footnote{Customarily, the system compiler
is also termed the @file{stage0} GCC.}.
You will invoke this target if you need to test or debug the
stage@var{N} GCC@. If you only need to execute GCC (but you need
not run @samp{make} either to rebuild it or to run test suites),
you should be able to work directly in the @file{stage@var{N}-gcc}
directory. This makes it easier to debug multiple stages in
parallel.
@item stage
For each package that is bootstrapped, relocate its build directory
to indicate its stage. For example, if the @file{gcc} directory
points to the stage2 GCC, after invoking this target it will be
renamed to @file{stage2-gcc}.
@end table
If you wish to use non-default GCC flags when compiling the stage2 and
stage3 compilers, set @code{BOOT_CFLAGS} on the command line when doing
@samp{make}.
Usually, the first stage only builds the languages that the compiler
is written in: typically, C and maybe Ada. If you are debugging a
miscompilation of a different stage2 front-end (for example, of the
Fortran front-end), you may want to have front-ends for other languages
in the first stage as well. To do so, set @code{STAGE1_LANGUAGES}
on the command line when doing @samp{make}.
For example, in the aforementioned scenario of debugging a Fortran
front-end miscompilation caused by the stage1 compiler, you may need a
command like
@example
make stage2-bubble STAGE1_LANGUAGES=c,fortran
@end example
Alternatively, you can use per-language targets to build and test
languages that are not enabled by default in stage1. For example,
@command{make f951} will build a Fortran compiler even in the stage1
build directory.

453
gcc/doc/match-and-simplify.texi Normal file
View File

@ -0,0 +1,453 @@
@c Copyright (C) 2014-2022 Free Software Foundation, Inc.
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Match and Simplify
@chapter Match and Simplify
@cindex Match and Simplify
The GIMPLE and GENERIC pattern matching project match-and-simplify
tries to address several issues.
@enumerate
@item unify expression simplifications currently spread and duplicated
over separate files like fold-const.cc, gimple-fold.cc and builtins.cc
@item allow for a cheap way to implement building and simplifying
non-trivial GIMPLE expressions, avoiding the need to go through
building and simplifying GENERIC via fold_buildN and then
gimplifying via force_gimple_operand
@end enumerate
To address these the project introduces a simple domain-specific language
to write expression simplifications from which code targeting GIMPLE
and GENERIC is auto-generated. The GENERIC variant follows the
fold_buildN API while for the GIMPLE variant and to address 2) new
APIs are introduced.
@menu
* GIMPLE API::
* The Language::
@end menu
@node GIMPLE API
@section GIMPLE API
@cindex GIMPLE API
@deftypefn {GIMPLE function} tree gimple_simplify (enum tree_code, tree, tree, gimple_seq *, tree (*)(tree))
@deftypefnx {GIMPLE function} tree gimple_simplify (enum tree_code, tree, tree, tree, gimple_seq *, tree (*)(tree))
@deftypefnx {GIMPLE function} tree gimple_simplify (enum tree_code, tree, tree, tree, tree, gimple_seq *, tree (*)(tree))
@deftypefnx {GIMPLE function} tree gimple_simplify (enum built_in_function, tree, tree, gimple_seq *, tree (*)(tree))
@deftypefnx {GIMPLE function} tree gimple_simplify (enum built_in_function, tree, tree, tree, gimple_seq *, tree (*)(tree))
@deftypefnx {GIMPLE function} tree gimple_simplify (enum built_in_function, tree, tree, tree, tree, gimple_seq *, tree (*)(tree))
The main GIMPLE API entry to the expression simplifications mimicking
that of the GENERIC fold_@{unary,binary,ternary@} functions.
@end deftypefn
thus providing n-ary overloads for operation or function. The
additional arguments are a gimple_seq where built statements are
inserted on (if @code{NULL} then simplifications requiring new statements
are not performed) and a valueization hook that can be used to
tie simplifications to a SSA lattice.
In addition to those APIs @code{fold_stmt} is overloaded with
a valueization hook:
@deftypefn bool fold_stmt (gimple_stmt_iterator *, tree (*)(tree));
@end deftypefn
On top of these a @code{fold_buildN}-like API for GIMPLE is introduced:
@deftypefn {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree (*valueize) (tree) = NULL);
@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree, tree (*valueize) (tree) = NULL);
@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree, tree, tree (*valueize) (tree) = NULL);
@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum built_in_function, tree, tree, tree (*valueize) (tree) = NULL);
@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum built_in_function, tree, tree, tree, tree (*valueize) (tree) = NULL);
@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum built_in_function, tree, tree, tree, tree, tree (*valueize) (tree) = NULL);
@deftypefnx {GIMPLE function} tree gimple_convert (gimple_seq *, location_t, tree, tree);
@end deftypefn
which is supposed to replace @code{force_gimple_operand (fold_buildN (...), ...)}
and calls to @code{fold_convert}. Overloads without the @code{location_t}
argument exist. Built statements are inserted on the provided sequence
and simplification is performed using the optional valueization hook.
@node The Language
@section The Language
@cindex The Language
The language in which to write expression simplifications resembles
other domain-specific languages GCC uses. Thus it is lispy. Let's
start with an example from the match.pd file:
@smallexample
(simplify
(bit_and @@0 integer_all_onesp)
@@0)
@end smallexample
This example contains all required parts of an expression simplification.
A simplification is wrapped inside a @code{(simplify ...)} expression.
That contains at least two operands - an expression that is matched
with the GIMPLE or GENERIC IL and a replacement expression that is
returned if the match was successful.
Expressions have an operator ID, @code{bit_and} in this case. Expressions can
be lower-case tree codes with @code{_expr} stripped off or builtin
function code names in all-caps, like @code{BUILT_IN_SQRT}.
@code{@@n} denotes a so-called capture. It captures the operand and lets
you refer to it in other places of the match-and-simplify. In the
above example it is referred to in the replacement expression. Captures
are @code{@@} followed by a number or an identifier.
@smallexample
(simplify
(bit_xor @@0 @@0)
@{ build_zero_cst (type); @})
@end smallexample
In this example @code{@@0} is mentioned twice which constrains the matched
expression to have two equal operands. Usually matches are constrained
to equal types. If operands may be constants and conversions are involved,
matching by value might be preferred in which case use @code{@@@@0} to
denote a by-value match and the specific operand you want to refer to
in the result part. This example also introduces
operands written in C code. These can be used in the expression
replacements and are supposed to evaluate to a tree node which has to
be a valid GIMPLE operand (so you cannot generate expressions in C code).
@smallexample
(simplify
(trunc_mod integer_zerop@@0 @@1)
(if (!integer_zerop (@@1))
@@0))
@end smallexample
Here @code{@@0} captures the first operand of the trunc_mod expression
which is also predicated with @code{integer_zerop}. Expression operands
may be either expressions, predicates or captures. Captures
can be unconstrained or capture expressions or predicates.
This example introduces an optional operand of simplify,
the if-expression. This condition is evaluated after the
expression matched in the IL and is required to evaluate to true
to enable the replacement expression in the second operand
position. The expression operand of the @code{if} is a standard C
expression which may contain references to captures. The @code{if}
has an optional third operand which may contain the replacement
expression that is enabled when the condition evaluates to false.
A @code{if} expression can be used to specify a common condition
for multiple simplify patterns, avoiding the need
to repeat that multiple times:
@smallexample
(if (!TYPE_SATURATING (type)
&& !FLOAT_TYPE_P (type) && !FIXED_POINT_TYPE_P (type))
(simplify
(minus (plus @@0 @@1) @@0)
@@1)
(simplify
(minus (minus @@0 @@1) @@0)
(negate @@1)))
@end smallexample
Note that @code{if}s in outer position do not have the optional
else clause but instead have multiple then clauses.
Ifs can be nested.
There exists a @code{switch} expression which can be used to
chain conditions avoiding nesting @code{if}s too much:
@smallexample
(simplify
(simple_comparison @@0 REAL_CST@@1)
(switch
/* a CMP (-0) -> a CMP 0 */
(if (REAL_VALUE_MINUS_ZERO (TREE_REAL_CST (@@1)))
(cmp @@0 @{ build_real (TREE_TYPE (@@1), dconst0); @}))
/* x != NaN is always true, other ops are always false. */
(if (REAL_VALUE_ISNAN (TREE_REAL_CST (@@1))
&& ! HONOR_SNANS (@@1))
@{ constant_boolean_node (cmp == NE_EXPR, type); @})))
@end smallexample
Is equal to
@smallexample
(simplify
(simple_comparison @@0 REAL_CST@@1)
(switch
/* a CMP (-0) -> a CMP 0 */
(if (REAL_VALUE_MINUS_ZERO (TREE_REAL_CST (@@1)))
(cmp @@0 @{ build_real (TREE_TYPE (@@1), dconst0); @})
/* x != NaN is always true, other ops are always false. */
(if (REAL_VALUE_ISNAN (TREE_REAL_CST (@@1))
&& ! HONOR_SNANS (@@1))
@{ constant_boolean_node (cmp == NE_EXPR, type); @}))))
@end smallexample
which has the second @code{if} in the else operand of the first.
The @code{switch} expression takes @code{if} expressions as
operands (which may not have else clauses) and as a last operand
a replacement expression which should be enabled by default if
no other condition evaluated to true.
Captures can also be used for capturing results of sub-expressions.
@smallexample
#if GIMPLE
(simplify
(pointer_plus (addr@@2 @@0) INTEGER_CST_P@@1)
(if (is_gimple_min_invariant (@@2)))
@{
poly_int64 off;
tree base = get_addr_base_and_unit_offset (@@0, &off);
off += tree_to_uhwi (@@1);
/* Now with that we should be able to simply write
(addr (mem_ref (addr @@base) (plus @@off @@1))) */
build1 (ADDR_EXPR, type,
build2 (MEM_REF, TREE_TYPE (TREE_TYPE (@@2)),
build_fold_addr_expr (base),
build_int_cst (ptr_type_node, off)));
@})
#endif
@end smallexample
In the above example, @code{@@2} captures the result of the expression
@code{(addr @@0)}. For the outermost expression only its type can be
captured, and the keyword @code{type} is reserved for this purpose. The
above example also gives a way to conditionalize patterns to only apply
to @code{GIMPLE} or @code{GENERIC} by means of using the pre-defined
preprocessor macros @code{GIMPLE} and @code{GENERIC} and using
preprocessor directives.
@smallexample
(simplify
(bit_and:c integral_op_p@@0 (bit_ior:c (bit_not @@0) @@1))
(bit_and @@1 @@0))
@end smallexample
Here we introduce flags on match expressions. The flag used
above, @code{c}, denotes that the expression should
be also matched commutated. Thus the above match expression
is really the following four match expressions:
@smallexample
(bit_and integral_op_p@@0 (bit_ior (bit_not @@0) @@1))
(bit_and (bit_ior (bit_not @@0) @@1) integral_op_p@@0)
(bit_and integral_op_p@@0 (bit_ior @@1 (bit_not @@0)))
(bit_and (bit_ior @@1 (bit_not @@0)) integral_op_p@@0)
@end smallexample
Usual canonicalizations you know from GENERIC expressions are
applied before matching, so for example constant operands always
come second in commutative expressions.
The second supported flag is @code{s} which tells the code
generator to fail the pattern if the expression marked with
@code{s} does have more than one use and the simplification
results in an expression with more than one operator.
For example in
@smallexample
(simplify
(pointer_plus (pointer_plus:s @@0 @@1) @@3)
(pointer_plus @@0 (plus @@1 @@3)))
@end smallexample
this avoids the association if @code{(pointer_plus @@0 @@1)} is
used outside of the matched expression and thus it would stay
live and not trivially removed by dead code elimination.
Now consider @code{((x + 3) + -3)} with the temporary
holding @code{(x + 3)} used elsewhere. This simplifies down
to @code{x} which is desirable and thus flagging with @code{s}
does not prevent the transform. Now consider @code{((x + 3) + 1)}
which simplifies to @code{(x + 4)}. Despite being flagged with
@code{s} the simplification will be performed. The
simplification of @code{((x + a) + 1)} to @code{(x + (a + 1))} will
not performed in this case though.
More features exist to avoid too much repetition.
@smallexample
(for op (plus pointer_plus minus bit_ior bit_xor)
(simplify
(op @@0 integer_zerop)
@@0))
@end smallexample
A @code{for} expression can be used to repeat a pattern for each
operator specified, substituting @code{op}. @code{for} can be
nested and a @code{for} can have multiple operators to iterate.
@smallexample
(for opa (plus minus)
opb (minus plus)
(for opc (plus minus)
(simplify...
@end smallexample
In this example the pattern will be repeated four times with
@code{opa, opb, opc} being @code{plus, minus, plus};
@code{plus, minus, minus}; @code{minus, plus, plus};
@code{minus, plus, minus}.
To avoid repeating operator lists in @code{for} you can name
them via
@smallexample
(define_operator_list pmm plus minus mult)
@end smallexample
and use them in @code{for} operator lists where they get expanded.
@smallexample
(for opa (pmm trunc_div)
(simplify...
@end smallexample
So this example iterates over @code{plus}, @code{minus}, @code{mult}
and @code{trunc_div}.
Using operator lists can also remove the need to explicitly write
a @code{for}. All operator list uses that appear in a @code{simplify}
or @code{match} pattern in operator positions will implicitly
be added to a new @code{for}. For example
@smallexample
(define_operator_list SQRT BUILT_IN_SQRTF BUILT_IN_SQRT BUILT_IN_SQRTL)
(define_operator_list POW BUILT_IN_POWF BUILT_IN_POW BUILT_IN_POWL)
(simplify
(SQRT (POW @@0 @@1))
(POW (abs @@0) (mult @@1 @{ built_real (TREE_TYPE (@@1), dconsthalf); @})))
@end smallexample
is the same as
@smallexample
(for SQRT (BUILT_IN_SQRTF BUILT_IN_SQRT BUILT_IN_SQRTL)
POW (BUILT_IN_POWF BUILT_IN_POW BUILT_IN_POWL)
(simplify
(SQRT (POW @@0 @@1))
(POW (abs @@0) (mult @@1 @{ built_real (TREE_TYPE (@@1), dconsthalf); @}))))
@end smallexample
@code{for}s and operator lists can include the special identifier
@code{null} that matches nothing and can never be generated. This can
be used to pad an operator list so that it has a standard form,
even if there isn't a suitable operator for every form.
Another building block are @code{with} expressions in the
result expression which nest the generated code in a new C block
followed by its argument:
@smallexample
(simplify
(convert (mult @@0 @@1))
(with @{ tree utype = unsigned_type_for (type); @}
(convert (mult (convert:utype @@0) (convert:utype @@1)))))
@end smallexample
This allows code nested in the @code{with} to refer to the declared
variables. In the above case we use the feature to specify the
type of a generated expression with the @code{:type} syntax where
@code{type} needs to be an identifier that refers to the desired type.
Usually the types of the generated result expressions are
determined from the context, but sometimes like in the above case
it is required that you specify them explicitly.
Another modifier for generated expressions is @code{!} which
tells the machinery to only consider the simplification in case
the marked expression simplified to a simple operand. Consider
for example
@smallexample
(simplify
(plus (vec_cond:s @@0 @@1 @@2) @@3)
(vec_cond @@0 (plus! @@1 @@3) (plus! @@2 @@3)))
@end smallexample
which moves the outer @code{plus} operation to the inner arms
of the @code{vec_cond} expression but only if the actual plus
operations both simplify. Note that on @code{GENERIC} a simple
operand means that the result satisfies @code{!EXPR_P} which
can be limiting if the operation itself simplifies but the
remaining operand is an (unrelated) expression.
As intermediate conversions are often optional there is a way to
avoid the need to repeat patterns both with and without such
conversions. Namely you can mark a conversion as being optional
with a @code{?}:
@smallexample
(simplify
(eq (convert@@0 @@1) (convert@? @@2))
(eq @@1 (convert @@2)))
@end smallexample
which will match both @code{(eq (convert @@1) (convert @@2))} and
@code{(eq (convert @@1) @@2)}. The optional converts are supposed
to be all either present or not, thus
@code{(eq (convert@? @@1) (convert@? @@2))} will result in two
patterns only. If you want to match all four combinations you
have access to two additional conditional converts as in
@code{(eq (convert1@? @@1) (convert2@? @@2))}.
The support for @code{?} marking extends to all unary operations
including predicates you declare yourself with @code{match}.
Predicates available from the GCC middle-end need to be made
available explicitly via @code{define_predicates}:
@smallexample
(define_predicates
integer_onep integer_zerop integer_all_onesp)
@end smallexample
You can also define predicates using the pattern matching language
and the @code{match} form:
@smallexample
(match negate_expr_p
INTEGER_CST
(if (TYPE_OVERFLOW_WRAPS (type)
|| may_negate_without_overflow_p (t))))
(match negate_expr_p
(negate @@0))
@end smallexample
This shows that for @code{match} expressions there is @code{t}
available which captures the outermost expression (something
not possible in the @code{simplify} context). As you can see
@code{match} has an identifier as first operand which is how
you refer to the predicate in patterns. Multiple @code{match}
for the same identifier add additional cases where the predicate
matches.
Predicates can also match an expression in which case you need
to provide a template specifying the identifier and where to
get its operands from:
@smallexample
(match (logical_inverted_value @@0)
(eq @@0 integer_zerop))
(match (logical_inverted_value @@0)
(bit_not truth_valued_p@@0))
@end smallexample
You can use the above predicate like
@smallexample
(simplify
(bit_and @@0 (logical_inverted_value @@0))
@{ build_zero_cst (type); @})
@end smallexample
Which will match a bitwise and of an operand with its logical
inverted value.

11679
gcc/doc/md.texi Normal file
View File

File diff suppressed because it is too large Load Diff

1210
gcc/doc/objc.texi Normal file
View File

File diff suppressed because it is too large Load Diff

246
gcc/doc/optinfo.texi Normal file
View File

@ -0,0 +1,246 @@
@c Copyright (C) 2013-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@cindex optimization dumps
This section is describes dump infrastructure which is common to both
pass dumps as well as optimization dumps. The goal for this
infrastructure is to provide both gcc developers and users detailed
information about various compiler transformations and optimizations.
@menu
* Dump setup:: Setup of optimization dumps.
* Optimization groups:: Groups made up of optimization passes.
* Dump files and streams:: Dump output file names and streams.
* Dump output verbosity:: How much information to dump.
* Dump types:: Various types of dump functions.
* Dump examples:: Sample usage.
@end menu
@node Dump setup
@subsection Dump setup
@cindex dump setup
A dump_manager class is defined in @file{dumpfile.h}. Various passes
register dumping pass-specific information via @code{dump_register} in
@file{passes.cc}. During the registration, an optimization pass can
select its optimization group (@pxref{Optimization groups}). After
that optimization information corresponding to the entire group
(presumably from multiple passes) can be output via command-line
switches. Note that if a pass does not fit into any of the pre-defined
groups, it can select @code{OPTGROUP_NONE}.
Note that in general, a pass need not know its dump output file name,
whether certain flags are enabled, etc. However, for legacy reasons,
passes could also call @code{dump_begin} which returns a stream in
case the particular pass has optimization dumps enabled. A pass could
call @code{dump_end} when the dump has ended. These methods should go
away once all the passes are converted to use the new dump
infrastructure.
The recommended way to setup the dump output is via @code{dump_start}
and @code{dump_end}.
@node Optimization groups
@subsection Optimization groups
@cindex optimization groups
The optimization passes are grouped into several categories. Currently
defined categories in @file{dumpfile.h} are
@ftable @code
@item OPTGROUP_IPA
IPA optimization passes. Enabled by @option{-ipa}
@item OPTGROUP_LOOP
Loop optimization passes. Enabled by @option{-loop}.
@item OPTGROUP_INLINE
Inlining passes. Enabled by @option{-inline}.
@item OPTGROUP_OMP
OMP (Offloading and Multi Processing) passes. Enabled by
@option{-omp}.
@item OPTGROUP_VEC
Vectorization passes. Enabled by @option{-vec}.
@item OPTGROUP_OTHER
All other optimization passes which do not fall into one of the above.
@item OPTGROUP_ALL
All optimization passes. Enabled by @option{-optall}.
@end ftable
By using groups a user could selectively enable optimization
information only for a group of passes. By default, the optimization
information for all the passes is dumped.
@node Dump files and streams
@subsection Dump files and streams
@cindex optimization info file names
There are two separate output streams available for outputting
optimization information from passes. Note that both these streams
accept @code{stderr} and @code{stdout} as valid streams and thus it is
possible to dump output to standard output or error. This is specially
handy for outputting all available information in a single file by
redirecting @code{stderr}.
@table @code
@item @code{pstream}
This stream is for pass-specific dump output. For example,
@option{-fdump-tree-vect=foo.v} dumps tree vectorization pass output
into the given file name @file{foo.v}. If the file name is not provided,
the default file name is based on the source file and pass number. Note
that one could also use special file names @code{stdout} and
@code{stderr} for dumping to standard output and standard error
respectively.
@item @code{alt_stream}
This steam is used for printing optimization specific output in
response to the @option{-fopt-info}. Again a file name can be given. If
the file name is not given, it defaults to @code{stderr}.
@end table
@node Dump output verbosity
@subsection Dump output verbosity
@cindex dump verbosity
The dump verbosity has the following options
@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 got
successfully vectorized.
@item missed
Print information about missed optimizations. Individual passes
control which information to include in the output. For example,
@smallexample
gcc -O2 -ftree-vectorize -fopt-info-vec-missed
@end smallexample
will print information about missed optimization opportunities from
vectorization passes on stderr.
@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
@var{optimized}, @var{missed}, and @var{note}.
@end table
@node Dump types
@subsection Dump types
@cindex dump types
@ftable @code
@item dump_printf
This is a generic method for doing formatted output. It takes an
additional argument @code{dump_kind} which signifies the type of
dump. This method outputs information only when the dumps are enabled
for this particular @code{dump_kind}. Note that the caller doesn't
need to know if the particular dump is enabled or not, or even the
file name. The caller only needs to decide which dump output
information is relevant, and under what conditions. This determines
the associated flags.
Consider the following example from @file{loop-unroll.cc} where an
informative message about a loop (along with its location) is printed
when any of the following flags is enabled
@itemize @minus
@item optimization messages
@item RTL dumps
@item detailed dumps
@end itemize
@example
int report_flags = MSG_OPTIMIZED_LOCATIONS | TDF_RTL | TDF_DETAILS;
dump_printf_loc (report_flags, insn,
"loop turned into non-loop; it never loops.\n");
@end example
@item dump_basic_block
Output basic block.
@item dump_generic_expr
Output generic expression.
@item dump_gimple_stmt
Output gimple statement.
Note that the above methods also have variants prefixed with
@code{_loc}, such as @code{dump_printf_loc}, which are similar except
they also output the source location information. The @code{_loc} variants
take a @code{const dump_location_t &}. This class can be constructed from
a @code{gimple *} or from a @code{rtx_insn *}, and so callers can pass
a @code{gimple *} or a @code{rtx_insn *} as the @code{_loc} argument.
The @code{dump_location_t} constructor will extract the source location
from the statement or instruction, along with the profile count, and
the location in GCC's own source code (or the plugin) from which the dump
call was emitted. Only the source location is currently used.
There is also a @code{dump_user_location_t} class, capturing the
source location and profile count, but not the dump emission location,
so that locations in the user's code can be passed around. This
can also be constructed from a @code{gimple *} and from a @code{rtx_insn *},
and it too can be passed as the @code{_loc} argument.
@end ftable
@node Dump examples
@subsection Dump examples
@cindex dump examples
@smallexample
gcc -O3 -fopt-info-missed=missed.all
@end smallexample
outputs missed optimization report from all the passes into
@file{missed.all}.
As another example,
@smallexample
gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
@end smallexample
will output information about missed optimizations as well as
optimized locations from all the inlining passes into
@file{inline.txt}.
If the @var{filename} is provided, then the dumps from all the
applicable optimizations are concatenated into the @file{filename}.
Otherwise the dump is output onto @file{stderr}. If @var{options} is
omitted, it defaults to @option{optimized-optall}, which means dump
all information about successful optimizations from all the passes.
In the following example, the optimization information is output on
to @file{stderr}.
@smallexample
gcc -O3 -fopt-info
@end smallexample
Note that @option{-fopt-info-vec-missed} behaves the same as
@option{-fopt-info-missed-vec}. The order of the optimization group
names and message types listed after @option{-fopt-info} does not matter.
As another example, consider
@smallexample
gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
@end smallexample
Here the two output file names @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 the @file{vec.miss} is produced which containts
dumps from the vectorizer about missed opportunities.

590
gcc/doc/options.texi Normal file
View File

@ -0,0 +1,590 @@
@c Copyright (C) 2003-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Options
@chapter Option specification files
@cindex option specification files
@cindex @samp{optc-gen.awk}
Most GCC command-line options are described by special option
definition files, the names of which conventionally end in
@code{.opt}. This chapter describes the format of these files.
@menu
* Option file format:: The general layout of the files
* Option properties:: Supported option properties
@end menu
@node Option file format
@section Option file format
Option files are a simple list of records in which each field occupies
its own line and in which the records themselves are separated by
blank lines. Comments may appear on their own line anywhere within
the file and are preceded by semicolons. Whitespace is allowed before
the semicolon.
The files can contain the following types of record:
@itemize @bullet
@item
A language definition record. These records have two fields: the
string @samp{Language} and the name of the language. Once a language
has been declared in this way, it can be used as an option property.
@xref{Option properties}.
@item
A target specific save record to save additional information. These
records have two fields: the string @samp{TargetSave}, and a
declaration type to go in the @code{cl_target_option} structure.
@item
A variable record to define a variable used to store option
information. These records have two fields: the string
@samp{Variable}, and a declaration of the type and name of the
variable, optionally with an initializer (but without any trailing
@samp{;}). These records may be used for variables used for many
options where declaring the initializer in a single option definition
record, or duplicating it in many records, would be inappropriate, or
for variables set in option handlers rather than referenced by
@code{Var} properties.
@item
A variable record to define a variable used to store option
information. These records have two fields: the string
@samp{TargetVariable}, and a declaration of the type and name of the
variable, optionally with an initializer (but without any trailing
@samp{;}). @samp{TargetVariable} is a combination of @samp{Variable}
and @samp{TargetSave} records in that the variable is defined in the
@code{gcc_options} structure, but these variables are also stored in
the @code{cl_target_option} structure. The variables are saved in the
target save code and restored in the target restore code.
@item
A variable record to record any additional files that the
@file{options.h} file should include. This is useful to provide
enumeration or structure definitions needed for target variables.
These records have two fields: the string @samp{HeaderInclude} and the
name of the include file.
@item
A variable record to record any additional files that the
@file{options.cc} or @file{options-save.cc} file should include. This
is useful to provide
inline functions needed for target variables and/or @code{#ifdef}
sequences to properly set up the initialization. These records have
two fields: the string @samp{SourceInclude} and the name of the
include file.
@item
An enumeration record to define a set of strings that may be used as
arguments to an option or options. These records have three fields:
the string @samp{Enum}, a space-separated list of properties and help
text used to describe the set of strings in @option{--help} output.
Properties use the same format as option properties; the following are
valid:
@table @code
@item Name(@var{name})
This property is required; @var{name} must be a name (suitable for use
in C identifiers) used to identify the set of strings in @code{Enum}
option properties.
@item Type(@var{type})
This property is required; @var{type} is the C type for variables set
by options using this enumeration together with @code{Var}.
@item UnknownError(@var{message})
The message @var{message} will be used as an error message if the
argument is invalid; for enumerations without @code{UnknownError}, a
generic error message is used. @var{message} should contain a single
@samp{%qs} format, which will be used to format the invalid argument.
@end table
@item
An enumeration value record to define one of the strings in a set
given in an @samp{Enum} record. These records have two fields: the
string @samp{EnumValue} and a space-separated list of properties.
Properties use the same format as option properties; the following are
valid:
@table @code
@item Enum(@var{name})
This property is required; @var{name} says which @samp{Enum} record
this @samp{EnumValue} record corresponds to.
@item String(@var{string})
This property is required; @var{string} is the string option argument
being described by this record.
@item Value(@var{value})
This property is required; it says what value (representable as
@code{int}) should be used for the given string.
@item Canonical
This property is optional. If present, it says the present string is
the canonical one among all those with the given value. Other strings
yielding that value will be mapped to this one so specs do not need to
handle them.
@item DriverOnly
This property is optional. If present, the present string will only
be accepted by the driver. This is used for cases such as
@option{-march=native} that are processed by the driver so that
@samp{gcc -v} shows how the options chosen depended on the system on
which the compiler was run.
@item Set(@var{number})
This property is optional, required for enumerations used in
@code{EnumSet} options. @var{number} should be decimal number between
1 and 64 inclusive and divides the enumeration into a set of
sets of mutually exclusive arguments. Arguments with the same
@var{number} can't be specified together in the same option, but
arguments with different @var{number} can. @var{value} needs to be
chosen such that a mask of all @var{value} values from the same set
@var{number} bitwise ored doesn't overlap with masks for other sets.
When @code{-foption=arg_from_set1,arg_from_set4} and
@code{-fno-option=arg_from_set3} are used, the effect is that previous
value of the @code{Var} will get bits from set 1 and 4 masks cleared,
ored @code{Value} of @code{arg_from_set1} and @code{arg_from_set4}
and then will get bits from set 3 mask cleared.
@end table
@item
An option definition record. These records have the following fields:
@enumerate
@item
the name of the option, with the leading ``-'' removed
@item
a space-separated list of option properties (@pxref{Option properties})
@item
the help text to use for @option{--help} (omitted if the second field
contains the @code{Undocumented} property).
@end enumerate
By default, all options beginning with ``f'', ``W'' or ``m'' are
implicitly assumed to take a ``no-'' form. This form should not be
listed separately. If an option beginning with one of these letters
does not have a ``no-'' form, you can use the @code{RejectNegative}
property to reject it.
The help text is automatically line-wrapped before being displayed.
Normally the name of the option is printed on the left-hand side of
the output and the help text is printed on the right. However, if the
help text contains a tab character, the text to the left of the tab is
used instead of the option's name and the text to the right of the
tab forms the help text. This allows you to elaborate on what type
of argument the option takes.
There is no support for different help texts for different languages.
If an option is supported for multiple languages, use a generic
description that is correct for all of them.
If an option has multiple option definition records (in different
front ends' @file{*.opt} files, and/or @file{gcc/common.opt}, for
example), convention is to not duplicate the help text for each of
them, but instead put a comment like @code{; documented in common.opt}
in place of the help text for all but one of the multiple option
definition records.
@item
A target mask record. These records have one field of the form
@samp{Mask(@var{x})}. The options-processing script will automatically
allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for
each mask name @var{x} and set the macro @code{MASK_@var{x}} to the
appropriate bitmask. It will also declare a @code{TARGET_@var{x}}
macro that has the value 1 when bit @code{MASK_@var{x}} is set and
0 otherwise.
They are primarily intended to declare target masks that are not
associated with user options, either because these masks represent
internal switches or because the options are not available on all
configurations and yet the masks always need to be defined.
@end itemize
@node Option properties
@section Option properties
The second field of an option record can specify any of the following
properties. When an option takes an argument, it is enclosed in parentheses
following the option property name. The parser that handles option files
is quite simplistic, and will be tricked by any nested parentheses within
the argument text itself; in this case, the entire option argument can
be wrapped in curly braces within the parentheses to demarcate it, e.g.:
@smallexample
Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@})
@end smallexample
@table @code
@item Common
The option is available for all languages and targets.
@item Target
The option is available for all languages but is target-specific.
@item Driver
The option is handled by the compiler driver using code not shared
with the compilers proper (@file{cc1} etc.).
@item @var{language}
The option is available when compiling for the given language.
It is possible to specify several different languages for the same
option. Each @var{language} must have been declared by an earlier
@code{Language} record. @xref{Option file format}.
@item RejectDriver
The option is only handled by the compilers proper (@file{cc1} etc.)@:
and should not be accepted by the driver.
@item RejectNegative
The option does not have a ``no-'' form. All options beginning with
``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this
property is used.
@item Negative(@var{othername})
The option will turn off another option @var{othername}, which is
the option name with the leading ``-'' removed. This chain action will
propagate through the @code{Negative} property of the option to be
turned off. The driver will prune options, removing those that are
turned off by some later option. This pruning is not done for options
with @code{Joined} or @code{JoinedOrMissing} properties, unless the
options have both the @code{RejectNegative} property and the @code{Negative}
property mentions itself.
As a consequence, if you have a group of mutually-exclusive
options, their @code{Negative} properties should form a circular chain.
For example, if options @option{-@var{a}}, @option{-@var{b}} and
@option{-@var{c}} are mutually exclusive, their respective @code{Negative}
properties should be @samp{Negative(@var{b})}, @samp{Negative(@var{c})}
and @samp{Negative(@var{a})}.
@item Joined
@itemx Separate
The option takes a mandatory argument. @code{Joined} indicates
that the option and argument can be included in the same @code{argv}
entry (as with @code{-mflush-func=@var{name}}, for example).
@code{Separate} indicates that the option and argument can be
separate @code{argv} entries (as with @code{-o}). An option is
allowed to have both of these properties.
@item JoinedOrMissing
The option takes an optional argument. If the argument is given,
it will be part of the same @code{argv} entry as the option itself.
This property cannot be used alongside @code{Joined} or @code{Separate}.
@item MissingArgError(@var{message})
For an option marked @code{Joined} or @code{Separate}, the message
@var{message} will be used as an error message if the mandatory
argument is missing; for options without @code{MissingArgError}, a
generic error message is used. @var{message} should contain a single
@samp{%qs} format, which will be used to format the name of the option
passed.
@item Args(@var{n})
For an option marked @code{Separate}, indicate that it takes @var{n}
arguments. The default is 1.
@item UInteger
The option's argument is a non-negative integer consisting of either
decimal or hexadecimal digits interpreted as @code{int}. Hexadecimal
integers may optionally start with the @code{0x} or @code{0X} prefix.
The option parser validates and converts the argument before passing
it to the relevant option handler. @code{UInteger} should also be used
with options like @code{-falign-loops} where both @code{-falign-loops}
and @code{-falign-loops}=@var{n} are supported to make sure the saved
options are given a full integer. Positive values of the argument in
excess of @code{INT_MAX} wrap around zero.
@item Host_Wide_Int
The option's argument is a non-negative integer consisting of either
decimal or hexadecimal digits interpreted as the widest integer type
on the host. As with an @code{UInteger} argument, hexadecimal integers
may optionally start with the @code{0x} or @code{0X} prefix. The option
parser validates and converts the argument before passing it to
the relevant option handler. @code{Host_Wide_Int} should be used with
options that need to accept very large values. Positive values of
the argument in excess of @code{HOST_WIDE_INT_M1U} are assigned
@code{HOST_WIDE_INT_M1U}.
@item IntegerRange(@var{n}, @var{m})
The options's arguments are integers of type @code{int}. The option's
parser validates that the value of an option integer argument is within
the closed range [@var{n}, @var{m}].
@item ByteSize
A property applicable only to @code{UInteger} or @code{Host_Wide_Int}
arguments. The option's integer argument is interpreted as if in infinite
precision using saturation arithmetic in the corresponding type. The argument
may be followed by a @samp{byte-size} suffix designating a multiple of bytes
such as @code{kB} and @code{KiB} for kilobyte and kibibyte, respectively,
@code{MB} and @code{MiB} for megabyte and mebibyte, @code{GB} and @code{GiB}
for gigabyte and gigibyte, and so on. @code{ByteSize} should be used for
with options that take a very large argument representing a size in bytes,
such as @option{-Wlarger-than=}.
@item ToLower
The option's argument should be converted to lowercase as part of
putting it in canonical form, and before comparing with the strings
indicated by any @code{Enum} property.
@item NoDriverArg
For an option marked @code{Separate}, the option only takes an
argument in the compiler proper, not in the driver. This is for
compatibility with existing options that are used both directly and
via @option{-Wp,}; new options should not have this property.
@item Var(@var{var})
The state of this option should be stored in variable @var{var}
(actually a macro for @code{global_options.x_@var{var}}).
The way that the state is stored depends on the type of option:
@item WarnRemoved
The option is removed and every usage of such option will
result in a warning. We use it option backward compatibility.
@item Var(@var{var}, @var{set})
The option controls an integer variable @var{var} and is active when
@var{var} equals @var{set}. The option parser will set @var{var} to
@var{set} when the positive form of the option is used and @code{!@var{set}}
when the ``no-'' form is used.
@var{var} is declared in the same way as for the single-argument form
described above.
@itemize @bullet
@item
If the option uses the @code{Mask} or @code{InverseMask} properties,
@var{var} is the integer variable that contains the mask.
@item
If the option is a normal on/off switch, @var{var} is an integer
variable that is nonzero when the option is enabled. The options
parser will set the variable to 1 when the positive form of the
option is used and 0 when the ``no-'' form is used.
@item
If the option takes an argument and has the @code{UInteger} property,
@var{var} is an integer variable that stores the value of the argument.
@item
If the option takes an argument and has the @code{Enum} property,
@var{var} is a variable (type given in the @code{Type} property of the
@samp{Enum} record whose @code{Name} property has the same argument as
the @code{Enum} property of this option) that stores the value of the
argument.
@item
If the option has the @code{Defer} property, @var{var} is a pointer to
a @code{VEC(cl_deferred_option,heap)} that stores the option for later
processing. (@var{var} is declared with type @code{void *} and needs
to be cast to @code{VEC(cl_deferred_option,heap)} before use.)
@item
Otherwise, if the option takes an argument, @var{var} is a pointer to
the argument string. The pointer will be null if the argument is optional
and wasn't given.
@end itemize
The option-processing script will usually zero-initialize @var{var}.
You can modify this behavior using @code{Init}.
@item Init(@var{value})
The variable specified by the @code{Var} property should be statically
initialized to @var{value}. If more than one option using the same
variable specifies @code{Init}, all must specify the same initializer.
@item Mask(@var{name})
The option is associated with a bit in the @code{target_flags}
variable (@pxref{Run-time Target}) and is active when that bit is set.
You may also specify @code{Var} to select a variable other than
@code{target_flags}.
The options-processing script will automatically allocate a unique bit
for the option. If the option is attached to @samp{target_flags},
the script will set the macro @code{MASK_@var{name}} to the appropriate
bitmask. It will also declare a @code{TARGET_@var{name}} macro that has
the value 1 when the option is active and 0 otherwise. If you use @code{Var}
to attach the option to a different variable, the bitmask macro with be
called @code{OPTION_MASK_@var{name}}.
@item InverseMask(@var{othername})
@itemx InverseMask(@var{othername}, @var{thisname})
The option is the inverse of another option that has the
@code{Mask(@var{othername})} property. If @var{thisname} is given,
the options-processing script will declare a @code{TARGET_@var{thisname}}
macro that is 1 when the option is active and 0 otherwise.
@item Enum(@var{name})
The option's argument is a string from the set of strings associated
with the corresponding @samp{Enum} record. The string is checked and
converted to the integer specified in the corresponding
@samp{EnumValue} record before being passed to option handlers.
@item EnumSet
Must be used together with the @code{Enum(@var{name})} property.
Corresponding @samp{Enum} record must use @code{Set} properties.
The option's argument is either a string from the set like for
@code{Enum(@var{name})}, but with a slightly different behavior that
the whole @code{Var} isn't overwritten, but only the bits in all the
enumeration values with the same set bitwise ored together.
Or option's argument can be a comma separated list of strings where
each string is from a different @code{Set(@var{number})}.
@item EnumBitSet
Must be used together with the @code{Enum(@var{name})} property.
Similar to @samp{EnumSet}, but corresponding @samp{Enum} record must
not use @code{Set} properties, each @code{EnumValue} should have
@code{Value} that is a power of 2, each value is treated as its own
set and its value as the set's mask, so there are no mutually
exclusive arguments.
@item Defer
The option should be stored in a vector, specified with @code{Var},
for later processing.
@item Alias(@var{opt})
@itemx Alias(@var{opt}, @var{arg})
@itemx Alias(@var{opt}, @var{posarg}, @var{negarg})
The option is an alias for @option{-@var{opt}} (or the negative form
of that option, depending on @code{NegativeAlias}). In the first form,
any argument passed to the alias is considered to be passed to
@option{-@var{opt}}, and @option{-@var{opt}} is considered to be
negated if the alias is used in negated form. In the second form, the
alias may not be negated or have an argument, and @var{posarg} is
considered to be passed as an argument to @option{-@var{opt}}. In the
third form, the alias may not have an argument, if the alias is used
in the positive form then @var{posarg} is considered to be passed to
@option{-@var{opt}}, and if the alias is used in the negative form
then @var{negarg} is considered to be passed to @option{-@var{opt}}.
Aliases should not specify @code{Var} or @code{Mask} or
@code{UInteger}. Aliases should normally specify the same languages
as the target of the alias; the flags on the target will be used to
determine any diagnostic for use of an option for the wrong language,
while those on the alias will be used to identify what command-line
text is the option and what text is any argument to that option.
When an @code{Alias} definition is used for an option, driver specs do
not need to handle it and no @samp{OPT_} enumeration value is defined
for it; only the canonical form of the option will be seen in those
places.
@item NegativeAlias
For an option marked with @code{Alias(@var{opt})}, the option is
considered to be an alias for the positive form of @option{-@var{opt}}
if negated and for the negative form of @option{-@var{opt}} if not
negated. @code{NegativeAlias} may not be used with the forms of
@code{Alias} taking more than one argument.
@item Ignore
This option is ignored apart from printing any warning specified using
@code{Warn}. The option will not be seen by specs and no @samp{OPT_}
enumeration value is defined for it.
@item SeparateAlias
For an option marked with @code{Joined}, @code{Separate} and
@code{Alias}, the option only acts as an alias when passed a separate
argument; with a joined argument it acts as a normal option, with an
@samp{OPT_} enumeration value. This is for compatibility with the
Java @option{-d} option and should not be used for new options.
@item Warn(@var{message})
If this option is used, output the warning @var{message}.
@var{message} is a format string, either taking a single operand with
a @samp{%qs} format which is the option name, or not taking any
operands, which is passed to the @samp{warning} function. If an alias
is marked @code{Warn}, the target of the alias must not also be marked
@code{Warn}.
@item Warning
This is a warning option and should be shown as such in
@option{--help} output. This flag does not currently affect anything
other than @option{--help}.
@item Optimization
This is an optimization option. It should be shown as such in
@option{--help} output, and any associated variable named using
@code{Var} should be saved and restored when the optimization level is
changed with @code{optimize} attributes.
@item PerFunction
This is an option that can be overridden on a per-function basis.
@code{Optimization} implies @code{PerFunction}, but options that do not
affect executable code generation may use this flag instead, so that the
option is not taken into account in ways that might affect executable
code generation.
@item Param
This is an option that is a parameter.
@item Undocumented
The option is deliberately missing documentation and should not
be included in the @option{--help} output.
@item Condition(@var{cond})
The option should only be accepted if preprocessor condition
@var{cond} is true. Note that any C declarations associated with the
option will be present even if @var{cond} is false; @var{cond} simply
controls whether the option is accepted and whether it is printed in
the @option{--help} output.
@item Save
Build the @code{cl_target_option} structure to hold a copy of the
option, add the functions @code{cl_target_option_save} and
@code{cl_target_option_restore} to save and restore the options.
@item SetByCombined
The option may also be set by a combined option such as
@option{-ffast-math}. This causes the @code{gcc_options} struct to
have a field @code{frontend_set_@var{name}}, where @code{@var{name}}
is the name of the field holding the value of this option (without the
leading @code{x_}). This gives the front end a way to indicate that
the value has been set explicitly and should not be changed by the
combined option. For example, some front ends use this to prevent
@option{-ffast-math} and @option{-fno-fast-math} from changing the
value of @option{-fmath-errno} for languages that do not use
@code{errno}.
@item EnabledBy(@var{opt})
@itemx EnabledBy(@var{opt} || @var{opt2})
@itemx EnabledBy(@var{opt} && @var{opt2})
If not explicitly set, the option is set to the value of
@option{-@var{opt}}; multiple options can be given, separated by
@code{||}. The third form using @code{&&} specifies that the option is
only set if both @var{opt} and @var{opt2} are set. The options @var{opt}
and @var{opt2} must have the @code{Common} property; otherwise, use
@code{LangEnabledBy}.
@item LangEnabledBy(@var{language}, @var{opt})
@itemx LangEnabledBy(@var{language}, @var{opt}, @var{posarg}, @var{negarg})
When compiling for the given language, the option is set to the value
of @option{-@var{opt}}, if not explicitly set. @var{opt} can be also a list
of @code{||} separated options. In the second form, if
@var{opt} is used in the positive form then @var{posarg} is considered
to be passed to the option, and if @var{opt} is used in the negative
form then @var{negarg} is considered to be passed to the option. It
is possible to specify several different languages. Each
@var{language} must have been declared by an earlier @code{Language}
record. @xref{Option file format}.
@item NoDWARFRecord
The option is omitted from the producer string written by
@option{-grecord-gcc-switches}.
@item PchIgnore
Even if this is a target option, this option will not be recorded / compared
to determine if a precompiled header file matches.
@item CPP(@var{var})
The state of this option should be kept in sync with the preprocessor
option @var{var}. If this property is set, then properties @code{Var}
and @code{Init} must be set as well.
@item CppReason(@var{CPP_W_Enum})
This warning option corresponds to @code{cpplib.h} warning reason code
@var{CPP_W_Enum}. This should only be used for warning options of the
C-family front-ends.
@end table

1196
gcc/doc/passes.texi Normal file
View File

File diff suppressed because it is too large Load Diff

562
gcc/doc/plugins.texi Normal file
View File

@ -0,0 +1,562 @@
@c Copyright (C) 2009-2022 Free Software Foundation, Inc.
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Plugins
@chapter Plugins
@cindex Plugins
GCC plugins are loadable modules that provide extra features to the
compiler. Like GCC itself they can be distributed in source and
binary forms.
GCC plugins provide developers with a rich subset of
the GCC API to allow them to extend GCC as they see fit.
Whether it is writing an additional optimization pass,
transforming code, or analyzing information, plugins
can be quite useful.
@menu
* Plugins loading:: How can we load plugins.
* Plugin API:: The APIs for plugins.
* Plugins pass:: How a plugin interact with the pass manager.
* Plugins GC:: How a plugin Interact with GCC Garbage Collector.
* Plugins description:: Giving information about a plugin itself.
* Plugins attr:: Registering custom attributes or pragmas.
* Plugins recording:: Recording information about pass execution.
* Plugins gate:: Controlling which passes are being run.
* Plugins tracking:: Keeping track of available passes.
* Plugins building:: How can we build a plugin.
@end menu
@node Plugins loading
@section Loading Plugins
Plugins are supported on platforms that support @option{-ldl
-rdynamic} as well as Windows/MinGW. They are loaded by the compiler
using @code{dlopen} or equivalent and invoked at pre-determined
locations in the compilation process.
Plugins are loaded with
@option{-fplugin=/path/to/@var{name}.@var{ext}} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]}
Where @var{name} is the plugin name and @var{ext} is the platform-specific
dynamic library extension. It should be @code{dll} on Windows/MinGW,
@code{dylib} on Darwin/Mac OS X, and @code{so} on all other platforms.
The plugin arguments are parsed by GCC and passed to respective
plugins as key-value pairs. Multiple plugins can be invoked by
specifying multiple @option{-fplugin} arguments.
A plugin can be simply given by its short name (no dots or
slashes). When simply passing @option{-fplugin=@var{name}}, the plugin is
loaded from the @file{plugin} directory, so @option{-fplugin=@var{name}} is
the same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.@var{ext}},
using backquote shell syntax to query the @file{plugin} directory.
@node Plugin API
@section Plugin API
Plugins are activated by the compiler at specific events as defined in
@file{gcc-plugin.h}. For each event of interest, the plugin should
call @code{register_callback} specifying the name of the event and
address of the callback function that will handle that event.
The header @file{gcc-plugin.h} must be the first gcc header to be included.
@subsection Plugin license check
Every plugin should define the global symbol @code{plugin_is_GPL_compatible}
to assert that it has been licensed under a GPL-compatible license.
If this symbol does not exist, the compiler will emit a fatal error
and exit with the error message:
@smallexample
fatal error: plugin @var{name} is not licensed under a GPL-compatible license
@var{name}: undefined symbol: plugin_is_GPL_compatible
compilation terminated
@end smallexample
The declared type of the symbol should be int, to match a forward declaration
in @file{gcc-plugin.h} that suppresses C++ mangling. It does not need to be in
any allocated section, though. The compiler merely asserts that
the symbol exists in the global scope. Something like this is enough:
@smallexample
int plugin_is_GPL_compatible;
@end smallexample
@subsection Plugin initialization
Every plugin should export a function called @code{plugin_init} that
is called right after the plugin is loaded. This function is
responsible for registering all the callbacks required by the plugin
and do any other required initialization.
This function is called from @code{compile_file} right before invoking
the parser. The arguments to @code{plugin_init} are:
@itemize @bullet
@item @code{plugin_info}: Plugin invocation information.
@item @code{version}: GCC version.
@end itemize
The @code{plugin_info} struct is defined as follows:
@smallexample
struct plugin_name_args
@{
char *base_name; /* Short name of the plugin
(filename without .so suffix). */
const char *full_name; /* Path to the plugin as specified with
-fplugin=. */
int argc; /* Number of arguments specified with
-fplugin-arg-.... */
struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
const char *version; /* Version string provided by plugin. */
const char *help; /* Help string provided by plugin. */
@}
@end smallexample
If initialization fails, @code{plugin_init} must return a non-zero
value. Otherwise, it should return 0.
The version of the GCC compiler loading the plugin is described by the
following structure:
@smallexample
struct plugin_gcc_version
@{
const char *basever;
const char *datestamp;
const char *devphase;
const char *revision;
const char *configuration_arguments;
@};
@end smallexample
The function @code{plugin_default_version_check} takes two pointers to
such structure and compare them field by field. It can be used by the
plugin's @code{plugin_init} function.
The version of GCC used to compile the plugin can be found in the symbol
@code{gcc_version} defined in the header @file{plugin-version.h}. The
recommended version check to perform looks like
@smallexample
#include "plugin-version.h"
...
int
plugin_init (struct plugin_name_args *plugin_info,
struct plugin_gcc_version *version)
@{
if (!plugin_default_version_check (version, &gcc_version))
return 1;
@}
@end smallexample
but you can also check the individual fields if you want a less strict check.
@subsection Plugin callbacks
Callback functions have the following prototype:
@smallexample
/* The prototype for a plugin callback function.
gcc_data - event-specific data provided by GCC
user_data - plugin-specific data provided by the plug-in. */
typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
@end smallexample
Callbacks can be invoked at the following pre-determined events:
@smallexample
enum plugin_event
@{
PLUGIN_START_PARSE_FUNCTION, /* Called before parsing the body of a function. */
PLUGIN_FINISH_PARSE_FUNCTION, /* After finishing parsing a function. */
PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */
PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */
PLUGIN_FINISH_DECL, /* After finishing parsing a declaration. */
PLUGIN_FINISH_UNIT, /* Useful for summary processing. */
PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */
PLUGIN_FINISH, /* Called before GCC exits. */
PLUGIN_INFO, /* Information about the plugin. */
PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */
PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
PLUGIN_GGC_END, /* Called at end of GGC. */
PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
PLUGIN_ATTRIBUTES, /* Called during attribute registration */
PLUGIN_START_UNIT, /* Called before processing a translation unit. */
PLUGIN_PRAGMAS, /* Called during pragma registration. */
/* Called before first pass from all_passes. */
PLUGIN_ALL_PASSES_START,
/* Called after last pass from all_passes. */
PLUGIN_ALL_PASSES_END,
/* Called before first ipa pass. */
PLUGIN_ALL_IPA_PASSES_START,
/* Called after last ipa pass. */
PLUGIN_ALL_IPA_PASSES_END,
/* Allows to override pass gate decision for current_pass. */
PLUGIN_OVERRIDE_GATE,
/* Called before executing a pass. */
PLUGIN_PASS_EXECUTION,
/* Called before executing subpasses of a GIMPLE_PASS in
execute_ipa_pass_list. */
PLUGIN_EARLY_GIMPLE_PASSES_START,
/* Called after executing subpasses of a GIMPLE_PASS in
execute_ipa_pass_list. */
PLUGIN_EARLY_GIMPLE_PASSES_END,
/* Called when a pass is first instantiated. */
PLUGIN_NEW_PASS,
/* Called when a file is #include-d or given via the #line directive.
This could happen many times. The event data is the included file path,
as a const char* pointer. */
PLUGIN_INCLUDE_FILE,
/* Called when -fanalyzer starts. The event data is an
ana::plugin_analyzer_init_iface *. */
PLUGIN_ANALYZER_INIT,
PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback
array. */
@};
@end smallexample
In addition, plugins can also look up the enumerator of a named event,
and / or generate new events dynamically, by calling the function
@code{get_named_event_id}.
To register a callback, the plugin calls @code{register_callback} with
the arguments:
@itemize
@item @code{char *name}: Plugin name.
@item @code{int event}: The event code.
@item @code{plugin_callback_func callback}: The function that handles @code{event}.
@item @code{void *user_data}: Pointer to plugin-specific data.
@end itemize
For the @i{PLUGIN_PASS_MANAGER_SETUP}, @i{PLUGIN_INFO}, and
@i{PLUGIN_REGISTER_GGC_ROOTS} pseudo-events the @code{callback} should be null,
and the @code{user_data} is specific.
When the @i{PLUGIN_PRAGMAS} event is triggered (with a null pointer as
data from GCC), plugins may register their own pragmas. Notice that
pragmas are not available from @file{lto1}, so plugins used with
@code{-flto} option to GCC during link-time optimization cannot use
pragmas and do not even see functions like @code{c_register_pragma} or
@code{pragma_lex}.
The @i{PLUGIN_INCLUDE_FILE} event, with a @code{const char*} file path as
GCC data, is triggered for processing of @code{#include} or
@code{#line} directives.
The @i{PLUGIN_FINISH} event is the last time that plugins can call GCC
functions, notably emit diagnostics with @code{warning}, @code{error}
etc.
@node Plugins pass
@section Interacting with the pass manager
There needs to be a way to add/reorder/remove passes dynamically. This
is useful for both analysis plugins (plugging in after a certain pass
such as CFG or an IPA pass) and optimization plugins.
Basic support for inserting new passes or replacing existing passes is
provided. A plugin registers a new pass with GCC by calling
@code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
event and a pointer to a @code{struct register_pass_info} object defined as follows
@smallexample
enum pass_positioning_ops
@{
PASS_POS_INSERT_AFTER, // Insert after the reference pass.
PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
PASS_POS_REPLACE // Replace the reference pass.
@};
struct register_pass_info
@{
struct opt_pass *pass; /* New pass provided by the plugin. */
const char *reference_pass_name; /* Name of the reference pass for hooking
up the new pass. */
int ref_pass_instance_number; /* Insert the pass at the specified
instance number of the reference pass. */
/* Do it for every instance if it is 0. */
enum pass_positioning_ops pos_op; /* how to insert the new pass. */
@};
/* Sample plugin code that registers a new pass. */
int
plugin_init (struct plugin_name_args *plugin_info,
struct plugin_gcc_version *version)
@{
struct register_pass_info pass_info;
...
/* Code to fill in the pass_info object with new pass information. */
...
/* Register the new pass. */
register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
...
@}
@end smallexample
@node Plugins GC
@section Interacting with the GCC Garbage Collector
Some plugins may want to be informed when GGC (the GCC Garbage
Collector) is running. They can register callbacks for the
@code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
the callback is called with a null @code{gcc_data}) to be notified of
the start or end of the GCC garbage collection.
Some plugins may need to have GGC mark additional data. This can be
done by registering a callback (called with a null @code{gcc_data})
for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
@code{ggc_set_mark} routine, preferably through the @code{ggc_mark} macro
(and conversely, these routines should usually not be used in plugins
outside of the @code{PLUGIN_GGC_MARKING} event). Plugins that wish to hold
weak references to gc data may also use this event to drop weak references when
the object is about to be collected. The @code{ggc_marked_p} function can be
used to tell if an object is marked, or is about to be collected. The
@code{gt_clear_cache} overloads which some types define may also be of use in
managing weak references.
Some plugins may need to add extra GGC root tables, e.g.@: to handle their own
@code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS}
pseudo-event with a null callback and the extra root table (of type @code{struct
ggc_root_tab*}) as @code{user_data}. Running the
@code{gengtype -p @var{source-dir} @var{file-list} @var{plugin*.c} ...}
utility generates these extra root tables.
You should understand the details of memory management inside GCC
before using @code{PLUGIN_GGC_MARKING} or @code{PLUGIN_REGISTER_GGC_ROOTS}.
@node Plugins description
@section Giving information about a plugin
A plugin should give some information to the user about itself. This
uses the following structure:
@smallexample
struct plugin_info
@{
const char *version;
const char *help;
@};
@end smallexample
Such a structure is passed as the @code{user_data} by the plugin's
init routine using @code{register_callback} with the
@code{PLUGIN_INFO} pseudo-event and a null callback.
@node Plugins attr
@section Registering custom attributes or pragmas
For analysis (or other) purposes it is useful to be able to add custom
attributes or pragmas.
The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
registration. Use the @code{register_attribute} function to register
custom attributes.
@smallexample
/* Attribute handler callback */
static tree
handle_user_attribute (tree *node, tree name, tree args,
int flags, bool *no_add_attrs)
@{
return NULL_TREE;
@}
/* Attribute definition */
static struct attribute_spec user_attr =
@{ "user", 1, 1, false, false, false, false, handle_user_attribute, NULL @};
/* Plugin callback called during attribute registration.
Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
*/
static void
register_attributes (void *event_data, void *data)
@{
warning (0, G_("Callback to register attributes"));
register_attribute (&user_attr);
@}
@end smallexample
The @i{PLUGIN_PRAGMAS} callback is called once during pragmas
registration. Use the @code{c_register_pragma},
@code{c_register_pragma_with_data},
@code{c_register_pragma_with_expansion},
@code{c_register_pragma_with_expansion_and_data} functions to register
custom pragmas and their handlers (which often want to call
@code{pragma_lex}) from @file{c-family/c-pragma.h}.
@smallexample
/* Plugin callback called during pragmas registration. Registered with
register_callback (plugin_name, PLUGIN_PRAGMAS,
register_my_pragma, NULL);
*/
static void
register_my_pragma (void *event_data, void *data)
@{
warning (0, G_("Callback to register pragmas"));
c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);
@}
@end smallexample
It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
your plugin) as the ``space'' argument of your pragma.
Pragmas registered with @code{c_register_pragma_with_expansion} or
@code{c_register_pragma_with_expansion_and_data} support
preprocessor expansions. For example:
@smallexample
#define NUMBER 10
#pragma GCCPLUGIN foothreshold (NUMBER)
@end smallexample
@node Plugins recording
@section Recording information about pass execution
The event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass
(the same as current_pass) as @code{gcc_data} to the callback. You can also
inspect cfun to find out about which function this pass is executed for.
Note that this event will only be invoked if the gate check (if
applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds.
You can use other hooks, like @code{PLUGIN_ALL_PASSES_START},
@code{PLUGIN_ALL_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START},
@code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START},
and/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state
in your plugin(s) in order to get context for the pass execution.
@node Plugins gate
@section Controlling which passes are being run
After the original gate function for a pass is called, its result
- the gate status - is stored as an integer.
Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer
to the gate status in the @code{gcc_data} parameter to the callback function.
A nonzero value of the gate status means that the pass is to be executed.
You can both read and write the gate status via the passed pointer.
@node Plugins tracking
@section Keeping track of available passes
When your plugin is loaded, you can inspect the various
pass lists to determine what passes are available. However, other
plugins might add new passes. Also, future changes to GCC might cause
generic passes to be added after plugin loading.
When a pass is first added to one of the pass lists, the event
@code{PLUGIN_NEW_PASS} is invoked, with the callback parameter
@code{gcc_data} pointing to the new pass.
@node Plugins building
@section Building GCC plugins
If plugins are enabled, GCC installs the headers needed to build a
plugin (somewhere in the installation tree, e.g.@: under
@file{/usr/local}). In particular a @file{plugin/include} directory
is installed, containing all the header files needed to build plugins.
On most systems, you can query this @code{plugin} directory by
invoking @command{gcc -print-file-name=plugin} (replace if needed
@command{gcc} with the appropriate program path).
Inside plugins, this @code{plugin} directory name can be queried by
calling @code{default_plugin_dir_name ()}.
Plugins may know, when they are compiled, the GCC version for which
@file{plugin-version.h} is provided. The constant macros
@code{GCCPLUGIN_VERSION_MAJOR}, @code{GCCPLUGIN_VERSION_MINOR},
@code{GCCPLUGIN_VERSION_PATCHLEVEL}, @code{GCCPLUGIN_VERSION} are
integer numbers, so a plugin could ensure it is built for GCC 4.7 with
@smallexample
#if GCCPLUGIN_VERSION != 4007
#error this GCC plugin is for GCC 4.7
#endif
@end smallexample
The following GNU Makefile excerpt shows how to build a simple plugin:
@smallexample
HOST_GCC=g++
TARGET_GCC=gcc
PLUGIN_SOURCE_FILES= plugin1.c plugin2.cc
GCCPLUGINS_DIR:= $(shell $(TARGET_GCC) -print-file-name=plugin)
CXXFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -fno-rtti -O2
plugin.so: $(PLUGIN_SOURCE_FILES)
$(HOST_GCC) -shared $(CXXFLAGS) $^ -o $@@
@end smallexample
A single source file plugin may be built with @code{g++ -I`gcc
-print-file-name=plugin`/include -fPIC -shared -fno-rtti -O2 plugin.cc -o
plugin.so}, using backquote shell syntax to query the @file{plugin}
directory.
Plugin support on Windows/MinGW has a number of limitations and
additional requirements. When building a plugin on Windows we have to
link an import library for the corresponding backend executable, for
example, @file{cc1.exe}, @file{cc1plus.exe}, etc., in order to gain
access to the symbols provided by GCC. This means that on Windows a
plugin is language-specific, for example, for C, C++, etc. If you wish
to use your plugin with multiple languages, then you will need to
build multiple plugin libraries and either instruct your users on how
to load the correct version or provide a compiler wrapper that does
this automatically.
Additionally, on Windows the plugin library has to export the
@code{plugin_is_GPL_compatible} and @code{plugin_init} symbols. If you
do not wish to modify the source code of your plugin, then you can use
the @option{-Wl,--export-all-symbols} option or provide a suitable DEF
file. Alternatively, you can export just these two symbols by decorating
them with @code{__declspec(dllexport)}, for example:
@smallexample
#ifdef _WIN32
__declspec(dllexport)
#endif
int plugin_is_GPL_compatible;
#ifdef _WIN32
__declspec(dllexport)
#endif
int plugin_init (plugin_name_args *, plugin_gcc_version *)
@end smallexample
The import libraries are installed into the @code{plugin} directory
and their names are derived by appending the @code{.a} extension to
the backend executable names, for example, @file{cc1.exe.a},
@file{cc1plus.exe.a}, etc. The following command line shows how to
build the single source file plugin on Windows to be used with the C++
compiler:
@smallexample
g++ -I`gcc -print-file-name=plugin`/include -shared -Wl,--export-all-symbols \
-o plugin.dll plugin.cc `gcc -print-file-name=plugin`/cc1plus.exe.a
@end smallexample
When a plugin needs to use @command{gengtype}, be sure that both
@file{gengtype} and @file{gtype.state} have the same version as the
GCC for which the plugin is built.

1060
gcc/doc/poly-int.texi Normal file
View File

File diff suppressed because it is too large Load Diff

39
gcc/doc/portability.texi Normal file
View File

@ -0,0 +1,39 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Portability
@chapter GCC and Portability
@cindex portability
@cindex GCC and portability
GCC itself aims to be portable to any machine where @code{int} is at least
a 32-bit type. It aims to target machines with a flat (non-segmented) byte
addressed data address space (the code address space can be separate).
Target ABIs may have 8, 16, 32 or 64-bit @code{int} type. @code{char}
can be wider than 8 bits.
GCC gets most of the information about the target machine from a machine
description which gives an algebraic formula for each of the machine's
instructions. This is a very clean way to describe the target. But when
the compiler needs information that is difficult to express in this
fashion, ad-hoc parameters have been defined for machine descriptions.
The purpose of portability is to reduce the total work needed on the
compiler; it was not of interest for its own sake.
@cindex endianness
@cindex autoincrement addressing, availability
@findex abort
GCC does not contain machine dependent code, but it does contain code
that depends on machine parameters such as endianness (whether the most
significant byte has the highest or lowest address of the bytes in a word)
and the availability of autoincrement addressing. In the RTL-generation
pass, it is often necessary to have multiple strategies for generating code
for a particular kind of syntax tree, strategies that are usable for different
combinations of parameters. Often, not all possible cases have been
addressed, but only the common ones or only the ones that have been
encountered. As a result, a new target may require additional
strategies. You will know
if this happens because the compiler will call @code{abort}. Fortunately,
the new strategies can be added in a machine-independent fashion, and will
affect only the target machines that need them.

5258
gcc/doc/rtl.texi Normal file
View File

File diff suppressed because it is too large Load Diff

27
gcc/doc/service.texi Normal file
View File

@ -0,0 +1,27 @@
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Service
@chapter How To Get Help with GCC
If you need help installing, using or changing GCC, there are two
ways to find it:
@itemize @bullet
@item
Send a message to a suitable network mailing list. First try
@email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
that brings no response, try @email{gcc@@gcc.gnu.org}. For help
changing GCC, ask @email{gcc@@gcc.gnu.org}. If you think you have found
a bug in GCC, please report it following the instructions at
@pxref{Bug Reporting}.
@item
Look in the service directory for someone who might help you for a fee.
The service directory is found at
@uref{https://www.fsf.org/resources/service}.
@end itemize
For further information, see
@uref{https://gcc.gnu.org/faq.html#support}.

3987
gcc/doc/sourcebuild.texi Normal file
View File

File diff suppressed because it is too large Load Diff

336
gcc/doc/standards.texi Normal file
View File

@ -0,0 +1,336 @@
@c Copyright (C) 2000-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Standards
@chapter Language Standards Supported by GCC
For each language compiled by GCC for which there is a standard, GCC
attempts to follow one or more versions of that standard, possibly
with some exceptions, and possibly with some extensions.
@section C Language
@cindex C standard
@cindex C standards
@cindex ANSI C standard
@cindex ANSI C
@cindex ANSI C89
@cindex C89
@cindex ANSI X3.159-1989
@cindex X3.159-1989
@cindex ISO C standard
@cindex ISO C
@cindex ISO C90
@cindex ISO/IEC 9899
@cindex ISO 9899
@cindex C90
@cindex ISO C94
@cindex C94
@cindex ISO C95
@cindex C95
@cindex ISO C99
@cindex C99
@cindex ISO C9X
@cindex C9X
@cindex ISO C11
@cindex C11
@cindex ISO C1X
@cindex C1X
@cindex ISO C17
@cindex C17
@cindex ISO C2X
@cindex C2X
@cindex Technical Corrigenda
@cindex TC1
@cindex Technical Corrigendum 1
@cindex TC2
@cindex Technical Corrigendum 2
@cindex TC3
@cindex Technical Corrigendum 3
@cindex AMD1
@cindex freestanding implementation
@cindex freestanding environment
@cindex hosted implementation
@cindex hosted environment
@findex __STDC_HOSTED__
@opindex std
@opindex ansi
@opindex pedantic
@opindex pedantic-errors
The original ANSI C standard (X3.159-1989) was ratified in 1989 and
published in 1990. This standard was ratified as an ISO standard
(ISO/IEC 9899:1990) later in 1990. There were no technical
differences between these publications, although the sections of the
ANSI standard were renumbered and became clauses in the ISO standard.
The ANSI
standard, but not the ISO standard, also came with a Rationale
document.
This standard, in both its forms, is commonly known as @dfn{C89}, or
occasionally as @dfn{C90}, from the dates of ratification.
To select this standard in GCC, use one of the options
@option{-ansi}, @option{-std=c90} or @option{-std=iso9899:1990}; to obtain
all the diagnostics required by the standard, you should also specify
@option{-pedantic} (or @option{-pedantic-errors} if you want them to be
errors rather than warnings). @xref{C Dialect Options,,Options
Controlling C Dialect}.
Errors in the 1990 ISO C standard were corrected in two Technical
Corrigenda published in 1994 and 1996. GCC does not support the
uncorrected version.
An amendment to the 1990 standard was published in 1995. This
amendment added digraphs and @code{__STDC_VERSION__} to the language,
but otherwise concerned the library. This amendment is commonly known
as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
@dfn{C95}. To select this standard in GCC, use the option
@option{-std=iso9899:199409} (with, as for other standard versions,
@option{-pedantic} to receive all required diagnostics).
A new edition of the ISO C standard was published in 1999 as ISO/IEC
9899:1999, and is commonly known as @dfn{C99}. (While in
development, drafts of this standard version were referred to as
@dfn{C9X}.) GCC has substantially
complete support for this standard version; see
@uref{https://gcc.gnu.org/c99status.html} for details. To select this
standard, use @option{-std=c99} or @option{-std=iso9899:1999}.
Errors in the 1999 ISO C standard were corrected in three Technical
Corrigenda published in 2001, 2004 and 2007. GCC does not support the
uncorrected version.
A fourth version of the C standard, known as @dfn{C11}, was published
in 2011 as ISO/IEC 9899:2011. (While in development, drafts of this
standard version were referred to as @dfn{C1X}.)
GCC has substantially complete support
for this standard, enabled with @option{-std=c11} or
@option{-std=iso9899:2011}. A version with corrections integrated was
prepared in 2017 and published in 2018 as ISO/IEC 9899:2018; it is
known as @dfn{C17} and is supported with @option{-std=c17} or
@option{-std=iso9899:2017}; the corrections are also applied with
@option{-std=c11}, and the only difference between the options is the
value of @code{__STDC_VERSION__}.
A further version of the C standard, known as @dfn{C2X}, is under
development; experimental and incomplete support for this is enabled
with @option{-std=c2x}.
By default, GCC provides some extensions to the C language that, on
rare occasions conflict with the C standard. @xref{C
Extensions,,Extensions to the C Language Family}.
Some features that are part of the C99 standard
are accepted as extensions in C90 mode, and some features that are part
of the C11 standard are accepted as extensions in C90 and C99 modes.
Use of the
@option{-std} options listed above disables these extensions where
they conflict with the C standard version selected. You may also
select an extended version of the C language explicitly with
@option{-std=gnu90} (for C90 with GNU extensions), @option{-std=gnu99}
(for C99 with GNU extensions) or @option{-std=gnu11} (for C11 with GNU
extensions).
The default, if no C language dialect options are given,
is @option{-std=gnu17}.
The ISO C standard defines (in clause 4) two classes of conforming
implementation. A @dfn{conforming hosted implementation} supports the
whole standard including all the library facilities; a @dfn{conforming
freestanding implementation} is only required to provide certain
library facilities: those in @code{<float.h>}, @code{<limits.h>},
@code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
@code{<iso646.h>}; since C99, also those in @code{<stdbool.h>} and
@code{<stdint.h>}; and since C11, also those in @code{<stdalign.h>}
and @code{<stdnoreturn.h>}. In addition, complex types, added in C99, are not
required for freestanding implementations.
The standard also defines two environments for programs, a
@dfn{freestanding environment}, required of all implementations and
which may not have library facilities beyond those required of
freestanding implementations, where the handling of program startup
and termination are implementation-defined; and a @dfn{hosted
environment}, which is not required, in which all the library
facilities are provided and startup is through a function @code{int
main (void)} or @code{int main (int, char *[])}. An OS kernel is an example
of a program running in a freestanding environment;
a program using the facilities of an
operating system is an example of a program running in a hosted environment.
@opindex ffreestanding
GCC aims towards being usable as a conforming freestanding
implementation, or as the compiler for a conforming hosted
implementation. By default, it acts as the compiler for a hosted
implementation, defining @code{__STDC_HOSTED__} as @code{1} and
presuming that when the names of ISO C functions are used, they have
the semantics defined in the standard. To make it act as a conforming
freestanding implementation for a freestanding environment, use the
option @option{-ffreestanding}; it then defines
@code{__STDC_HOSTED__} to @code{0} and does not make assumptions about the
meanings of function names from the standard library, with exceptions
noted below. To build an OS kernel, you may well still need to make
your own arrangements for linking and startup.
@xref{C Dialect Options,,Options Controlling C Dialect}.
GCC does not provide the library facilities required only of hosted
implementations, nor yet all the facilities required by C99 of
freestanding implementations on all platforms.
To use the facilities of a hosted
environment, you need to find them elsewhere (for example, in the
GNU C library). @xref{Standard Libraries,,Standard Libraries}.
Most of the compiler support routines used by GCC are present in
@file{libgcc}, but there are a few exceptions. GCC requires the
freestanding environment provide @code{memcpy}, @code{memmove},
@code{memset} and @code{memcmp}.
Finally, if @code{__builtin_trap} is used, and the target does
not implement the @code{trap} pattern, then GCC emits a call
to @code{abort}.
For references to Technical Corrigenda, Rationale documents and
information concerning the history of C that is available online, see
@uref{https://gcc.gnu.org/readings.html}
@section C++ Language
GCC supports the original ISO C++ standard published in 1998,
and the 2011, 2014, 2017 and mostly 2020 revisions.
The original ISO C++ standard was published as the ISO standard (ISO/IEC
14882:1998) and amended by a Technical Corrigenda published in 2003
(ISO/IEC 14882:2003). These standards are referred to as C++98 and
C++03, respectively. GCC implements the majority of C++98 (@code{export}
is a notable exception) and most of the changes in C++03. To select
this standard in GCC, use one of the options @option{-ansi},
@option{-std=c++98}, or @option{-std=c++03}; to obtain all the diagnostics
required by the standard, you should also specify @option{-pedantic} (or
@option{-pedantic-errors} if you want them to be errors rather than
warnings).
A revised ISO C++ standard was published in 2011 as ISO/IEC
14882:2011, and is referred to as C++11; before its publication it was
commonly referred to as C++0x. C++11 contains several changes to the
C++ language, all of which have been implemented in GCC@. For details
see @uref{https://gcc.gnu.org/projects/@/cxx-status.html#cxx11}.
To select this standard in GCC, use the option @option{-std=c++11}.
Another revised ISO C++ standard was published in 2014 as ISO/IEC
14882:2014, and is referred to as C++14; before its publication it was
sometimes referred to as C++1y. C++14 contains several further
changes to the C++ language, all of which have been implemented in GCC@.
For details see @uref{https://gcc.gnu.org/projects/@/cxx-status.html#cxx14}.
To select this standard in GCC, use the option @option{-std=c++14}.
The C++ language was further revised in 2017 and ISO/IEC 14882:2017 was
published. This is referred to as C++17, and before publication was
often referred to as C++1z. GCC supports all the changes in that
specification. For further details see
@uref{https://gcc.gnu.org/projects/@/cxx-status.html#cxx17}. Use the option
@option{-std=c++17} to select this variant of C++.
Another revised ISO C++ standard was published in 2020 as ISO/IEC
14882:2020, and is referred to as C++20; before its publication it was
sometimes referred to as C++2a. GCC supports most of the changes in the
new specification. For further details see
@uref{https://gcc.gnu.org/projects/@/cxx-status.html#cxx20}.
To select this standard in GCC, use the option @option{-std=c++20}.
More information about the C++ standards is available on the ISO C++
committee's web site at @uref{http://www.open-std.org/@/jtc1/@/sc22/@/wg21/}.
To obtain all the diagnostics required by any of the standard versions
described above you should specify @option{-pedantic}
or @option{-pedantic-errors}, otherwise GCC will allow some non-ISO C++
features as extensions. @xref{Warning Options}.
By default, GCC also provides some additional extensions to the C++ language
that on rare occasions conflict with the C++ standard. @xref{C++
Dialect Options,Options Controlling C++ Dialect}. Use of the
@option{-std} options listed above disables these extensions where they
they conflict with the C++ standard version selected. You may also
select an extended version of the C++ language explicitly with
@option{-std=gnu++98} (for C++98 with GNU extensions), or
@option{-std=gnu++11} (for C++11 with GNU extensions), or
@option{-std=gnu++14} (for C++14 with GNU extensions), or
@option{-std=gnu++17} (for C++17 with GNU extensions), or
@option{-std=gnu++20} (for C++20 with GNU extensions).
The default, if
no C++ language dialect options are given, is @option{-std=gnu++17}.
@section Objective-C and Objective-C++ Languages
@cindex Objective-C
@cindex Objective-C++
GCC supports ``traditional'' Objective-C (also known as ``Objective-C
1.0'') and contains support for the Objective-C exception and
synchronization syntax. It has also support for a number of
``Objective-C 2.0'' language extensions, including properties, fast
enumeration (only for Objective-C), method attributes and the
@@optional and @@required keywords in protocols. GCC supports
Objective-C++ and features available in Objective-C are also available
in Objective-C++@.
GCC by default uses the GNU Objective-C runtime library, which is part
of GCC and is not the same as the Apple/NeXT Objective-C runtime
library used on Apple systems. There are a number of differences
documented in this manual. The options @option{-fgnu-runtime} and
@option{-fnext-runtime} allow you to switch between producing output
that works with the GNU Objective-C runtime library and output that
works with the Apple/NeXT Objective-C runtime library.
There is no formal written standard for Objective-C or Objective-C++@.
The authoritative manual on traditional Objective-C (1.0) is
``Object-Oriented Programming and the Objective-C Language'':
@uref{http://www.gnustep.org/@/resources/@/documentation/@/ObjectivCBook.pdf}
is the original NeXTstep document.
The Objective-C exception and synchronization syntax (that is, the
keywords @code{@@try}, @code{@@throw}, @code{@@catch},
@code{@@finally} and @code{@@synchronized}) is
supported by GCC and is enabled with the option
@option{-fobjc-exceptions}. The syntax is briefly documented in this
manual and in the Objective-C 2.0 manuals from Apple.
The Objective-C 2.0 language extensions and features are automatically
enabled; they include properties (via the @code{@@property},
@code{@@synthesize} and
@code{@@dynamic keywords}), fast enumeration (not available in
Objective-C++), attributes for methods (such as @code{deprecated},
@code{noreturn}, @code{sentinel}, @code{format}),
the @code{unused} attribute for method arguments, the
@code{@@package} keyword for instance variables and the @code{@@optional} and
@code{@@required} keywords in protocols. You can disable all these
Objective-C 2.0 language extensions with the option
@option{-fobjc-std=objc1}, which causes the compiler to recognize the
same Objective-C language syntax recognized by GCC 4.0, and to produce
an error if one of the new features is used.
GCC has currently no support for non-fragile instance variables.
The authoritative manual on Objective-C 2.0 is available from Apple:
@itemize
@item
@uref{https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html}
@end itemize
For more information concerning the history of Objective-C that is
available online, see @uref{https://gcc.gnu.org/readings.html}
@section Go Language
As of the GCC 4.7.1 release, GCC supports the Go 1 language standard,
described at @uref{https://golang.org/doc/go1}.
@section D language
GCC supports the D 2.0 programming language. The D language itself is
currently defined by its reference implementation and supporting language
specification, described at @uref{https://dlang.org/spec/spec.html}.
@section References for Other Languages
@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm,
GNAT Reference Manual}, for information on standard
conformance and compatibility of the Ada compiler.
@xref{Standards,,Standards, gfortran, The GNU Fortran Compiler}, for details
of standards supported by GNU Fortran.

12436
gcc/doc/tm.texi Normal file
View File

File diff suppressed because it is too large Load Diff

7984
gcc/doc/tm.texi.in Normal file
View File

File diff suppressed because it is too large Load Diff

826
gcc/doc/tree-ssa.texi Normal file
View File

@ -0,0 +1,826 @@
@c Copyright (C) 2004-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@c ---------------------------------------------------------------------
@c Tree SSA
@c ---------------------------------------------------------------------
@node Tree SSA
@chapter Analysis and Optimization of GIMPLE tuples
@cindex Tree SSA
@cindex Optimization infrastructure for GIMPLE
GCC uses three main intermediate languages to represent the program
during compilation: GENERIC, GIMPLE and RTL@. GENERIC is a
language-independent representation generated by each front end. It
is used to serve as an interface between the parser and optimizer.
GENERIC is a common representation that is able to represent programs
written in all the languages supported by GCC@.
GIMPLE and RTL are used to optimize the program. GIMPLE is used for
target and language independent optimizations (e.g., inlining,
constant propagation, tail call elimination, redundancy elimination,
etc). Much like GENERIC, GIMPLE is a language independent, tree based
representation. However, it differs from GENERIC in that the GIMPLE
grammar is more restrictive: expressions contain no more than 3
operands (except function calls), it has no control flow structures
and expressions with side effects are only allowed on the right hand
side of assignments. See the chapter describing GENERIC and GIMPLE
for more details.
This chapter describes the data structures and functions used in the
GIMPLE optimizers (also known as ``tree optimizers'' or ``middle
end''). In particular, it focuses on all the macros, data structures,
functions and programming constructs needed to implement optimization
passes for GIMPLE@.
@menu
* Annotations:: Attributes for variables.
* SSA Operands:: SSA names referenced by GIMPLE statements.
* SSA:: Static Single Assignment representation.
* Alias analysis:: Representing aliased loads and stores.
* Memory model:: Memory model used by the middle-end.
@end menu
@node Annotations
@section Annotations
@cindex annotations
The optimizers need to associate attributes with variables during the
optimization process. For instance, we need to know whether a
variable has aliases. All these attributes are stored in data
structures called annotations which are then linked to the field
@code{ann} in @code{struct tree_common}.
@node SSA Operands
@section SSA Operands
@cindex operands
@cindex virtual operands
@cindex real operands
@findex update_stmt
Almost every GIMPLE statement will contain a reference to a variable
or memory location. Since statements come in different shapes and
sizes, their operands are going to be located at various spots inside
the statement's tree. To facilitate access to the statement's
operands, they are organized into lists associated inside each
statement's annotation. Each element in an operand list is a pointer
to a @code{VAR_DECL}, @code{PARM_DECL} or @code{SSA_NAME} tree node.
This provides a very convenient way of examining and replacing
operands.
Data flow analysis and optimization is done on all tree nodes
representing variables. Any node for which @code{SSA_VAR_P} returns
nonzero is considered when scanning statement operands. However, not
all @code{SSA_VAR_P} variables are processed in the same way. For the
purposes of optimization, we need to distinguish between references to
local scalar variables and references to globals, statics, structures,
arrays, aliased variables, etc. The reason is simple, the compiler
can gather complete data flow information for a local scalar. On the
other hand, a global variable may be modified by a function call, it
may not be possible to keep track of all the elements of an array or
the fields of a structure, etc.
The operand scanner gathers two kinds of operands: @dfn{real} and
@dfn{virtual}. An operand for which @code{is_gimple_reg} returns true
is considered real, otherwise it is a virtual operand. We also
distinguish between uses and definitions. An operand is used if its
value is loaded by the statement (e.g., the operand at the RHS of an
assignment). If the statement assigns a new value to the operand, the
operand is considered a definition (e.g., the operand at the LHS of
an assignment).
Virtual and real operands also have very different data flow
properties. Real operands are unambiguous references to the
full object that they represent. For instance, given
@smallexample
@{
int a, b;
a = b
@}
@end smallexample
Since @code{a} and @code{b} are non-aliased locals, the statement
@code{a = b} will have one real definition and one real use because
variable @code{a} is completely modified with the contents of
variable @code{b}. Real definition are also known as @dfn{killing
definitions}. Similarly, the use of @code{b} reads all its bits.
In contrast, virtual operands are used with variables that can have
a partial or ambiguous reference. This includes structures, arrays,
globals, and aliased variables. In these cases, we have two types of
definitions. For globals, structures, and arrays, we can determine from
a statement whether a variable of these types has a killing definition.
If the variable does, then the statement is marked as having a
@dfn{must definition} of that variable. However, if a statement is only
defining a part of the variable (i.e.@: a field in a structure), or if we
know that a statement might define the variable but we cannot say for sure,
then we mark that statement as having a @dfn{may definition}. For
instance, given
@smallexample
@{
int a, b, *p;
if (@dots{})
p = &a;
else
p = &b;
*p = 5;
return *p;
@}
@end smallexample
The assignment @code{*p = 5} may be a definition of @code{a} or
@code{b}. If we cannot determine statically where @code{p} is
pointing to at the time of the store operation, we create virtual
definitions to mark that statement as a potential definition site for
@code{a} and @code{b}. Memory loads are similarly marked with virtual
use operands. Virtual operands are shown in tree dumps right before
the statement that contains them. To request a tree dump with virtual
operands, use the @option{-vops} option to @option{-fdump-tree}:
@smallexample
@{
int a, b, *p;
if (@dots{})
p = &a;
else
p = &b;
# a = VDEF <a>
# b = VDEF <b>
*p = 5;
# VUSE <a>
# VUSE <b>
return *p;
@}
@end smallexample
Notice that @code{VDEF} operands have two copies of the referenced
variable. This indicates that this is not a killing definition of
that variable. In this case we refer to it as a @dfn{may definition}
or @dfn{aliased store}. The presence of the second copy of the
variable in the @code{VDEF} operand will become important when the
function is converted into SSA form. This will be used to link all
the non-killing definitions to prevent optimizations from making
incorrect assumptions about them.
Operands are updated as soon as the statement is finished via a call
to @code{update_stmt}. If statement elements are changed via
@code{SET_USE} or @code{SET_DEF}, then no further action is required
(i.e., those macros take care of updating the statement). If changes
are made by manipulating the statement's tree directly, then a call
must be made to @code{update_stmt} when complete. Calling one of the
@code{bsi_insert} routines or @code{bsi_replace} performs an implicit
call to @code{update_stmt}.
@subsection Operand Iterators And Access Routines
@cindex Operand Iterators
@cindex Operand Access Routines
Operands are collected by @file{tree-ssa-operands.cc}. They are stored
inside each statement's annotation and can be accessed through either the
operand iterators or an access routine.
The following access routines are available for examining operands:
@enumerate
@item @code{SINGLE_SSA_@{USE,DEF,TREE@}_OPERAND}: These accessors will return
NULL unless there is exactly one operand matching the specified flags. If
there is exactly one operand, the operand is returned as either a @code{tree},
@code{def_operand_p}, or @code{use_operand_p}.
@smallexample
tree t = SINGLE_SSA_TREE_OPERAND (stmt, flags);
use_operand_p u = SINGLE_SSA_USE_OPERAND (stmt, SSA_ALL_VIRTUAL_USES);
def_operand_p d = SINGLE_SSA_DEF_OPERAND (stmt, SSA_OP_ALL_DEFS);
@end smallexample
@item @code{ZERO_SSA_OPERANDS}: This macro returns true if there are no
operands matching the specified flags.
@smallexample
if (ZERO_SSA_OPERANDS (stmt, SSA_OP_ALL_VIRTUALS))
return;
@end smallexample
@item @code{NUM_SSA_OPERANDS}: This macro Returns the number of operands
matching 'flags'. This actually executes a loop to perform the count, so
only use this if it is really needed.
@smallexample
int count = NUM_SSA_OPERANDS (stmt, flags)
@end smallexample
@end enumerate
If you wish to iterate over some or all operands, use the
@code{FOR_EACH_SSA_@{USE,DEF,TREE@}_OPERAND} iterator. For example, to print
all the operands for a statement:
@smallexample
void
print_ops (tree stmt)
@{
ssa_op_iter;
tree var;
FOR_EACH_SSA_TREE_OPERAND (var, stmt, iter, SSA_OP_ALL_OPERANDS)
print_generic_expr (stderr, var, TDF_SLIM);
@}
@end smallexample
How to choose the appropriate iterator:
@enumerate
@item Determine whether you are need to see the operand pointers, or just the
trees, and choose the appropriate macro:
@smallexample
Need Macro:
---- -------
use_operand_p FOR_EACH_SSA_USE_OPERAND
def_operand_p FOR_EACH_SSA_DEF_OPERAND
tree FOR_EACH_SSA_TREE_OPERAND
@end smallexample
@item You need to declare a variable of the type you are interested
in, and an ssa_op_iter structure which serves as the loop controlling
variable.
@item Determine which operands you wish to use, and specify the flags of
those you are interested in. They are documented in
@file{tree-ssa-operands.h}:
@smallexample
#define SSA_OP_USE 0x01 /* @r{Real USE operands.} */
#define SSA_OP_DEF 0x02 /* @r{Real DEF operands.} */
#define SSA_OP_VUSE 0x04 /* @r{VUSE operands.} */
#define SSA_OP_VDEF 0x08 /* @r{VDEF operands.} */
/* @r{These are commonly grouped operand flags.} */
#define SSA_OP_VIRTUAL_USES (SSA_OP_VUSE)
#define SSA_OP_VIRTUAL_DEFS (SSA_OP_VDEF)
#define SSA_OP_ALL_VIRTUALS (SSA_OP_VIRTUAL_USES | SSA_OP_VIRTUAL_DEFS)
#define SSA_OP_ALL_USES (SSA_OP_VIRTUAL_USES | SSA_OP_USE)
#define SSA_OP_ALL_DEFS (SSA_OP_VIRTUAL_DEFS | SSA_OP_DEF)
#define SSA_OP_ALL_OPERANDS (SSA_OP_ALL_USES | SSA_OP_ALL_DEFS)
@end smallexample
@end enumerate
So if you want to look at the use pointers for all the @code{USE} and
@code{VUSE} operands, you would do something like:
@smallexample
use_operand_p use_p;
ssa_op_iter iter;
FOR_EACH_SSA_USE_OPERAND (use_p, stmt, iter, (SSA_OP_USE | SSA_OP_VUSE))
@{
process_use_ptr (use_p);
@}
@end smallexample
The @code{TREE} macro is basically the same as the @code{USE} and
@code{DEF} macros, only with the use or def dereferenced via
@code{USE_FROM_PTR (use_p)} and @code{DEF_FROM_PTR (def_p)}. Since we
aren't using operand pointers, use and defs flags can be mixed.
@smallexample
tree var;
ssa_op_iter iter;
FOR_EACH_SSA_TREE_OPERAND (var, stmt, iter, SSA_OP_VUSE)
@{
print_generic_expr (stderr, var, TDF_SLIM);
@}
@end smallexample
@code{VDEF}s are broken into two flags, one for the
@code{DEF} portion (@code{SSA_OP_VDEF}) and one for the USE portion
(@code{SSA_OP_VUSE}).
There are many examples in the code, in addition to the documentation
in @file{tree-ssa-operands.h} and @file{ssa-iterators.h}.
There are also a couple of variants on the stmt iterators regarding PHI
nodes.
@code{FOR_EACH_PHI_ARG} Works exactly like
@code{FOR_EACH_SSA_USE_OPERAND}, except it works over @code{PHI} arguments
instead of statement operands.
@smallexample
/* Look at every virtual PHI use. */
FOR_EACH_PHI_ARG (use_p, phi_stmt, iter, SSA_OP_VIRTUAL_USES)
@{
my_code;
@}
/* Look at every real PHI use. */
FOR_EACH_PHI_ARG (use_p, phi_stmt, iter, SSA_OP_USES)
my_code;
/* Look at every PHI use. */
FOR_EACH_PHI_ARG (use_p, phi_stmt, iter, SSA_OP_ALL_USES)
my_code;
@end smallexample
@code{FOR_EACH_PHI_OR_STMT_@{USE,DEF@}} works exactly like
@code{FOR_EACH_SSA_@{USE,DEF@}_OPERAND}, except it will function on
either a statement or a @code{PHI} node. These should be used when it is
appropriate but they are not quite as efficient as the individual
@code{FOR_EACH_PHI} and @code{FOR_EACH_SSA} routines.
@smallexample
FOR_EACH_PHI_OR_STMT_USE (use_operand_p, stmt, iter, flags)
@{
my_code;
@}
FOR_EACH_PHI_OR_STMT_DEF (def_operand_p, phi, iter, flags)
@{
my_code;
@}
@end smallexample
@subsection Immediate Uses
@cindex Immediate Uses
Immediate use information is now always available. Using the immediate use
iterators, you may examine every use of any @code{SSA_NAME}. For instance,
to change each use of @code{ssa_var} to @code{ssa_var2} and call fold_stmt on
each stmt after that is done:
@smallexample
use_operand_p imm_use_p;
imm_use_iterator iterator;
tree ssa_var, stmt;
FOR_EACH_IMM_USE_STMT (stmt, iterator, ssa_var)
@{
FOR_EACH_IMM_USE_ON_STMT (imm_use_p, iterator)
SET_USE (imm_use_p, ssa_var_2);
fold_stmt (stmt);
@}
@end smallexample
There are 2 iterators which can be used. @code{FOR_EACH_IMM_USE_FAST} is
used when the immediate uses are not changed, i.e., you are looking at the
uses, but not setting them.
If they do get changed, then care must be taken that things are not changed
under the iterators, so use the @code{FOR_EACH_IMM_USE_STMT} and
@code{FOR_EACH_IMM_USE_ON_STMT} iterators. They attempt to preserve the
sanity of the use list by moving all the uses for a statement into
a controlled position, and then iterating over those uses. Then the
optimization can manipulate the stmt when all the uses have been
processed. This is a little slower than the FAST version since it adds a
placeholder element and must sort through the list a bit for each statement.
This placeholder element must be also be removed if the loop is
terminated early; a destructor takes care of that when leaving the
@code{FOR_EACH_IMM_USE_STMT} scope.
There are checks in @code{verify_ssa} which verify that the immediate use list
is up to date, as well as checking that an optimization didn't break from the
loop without using this macro. It is safe to simply 'break'; from a
@code{FOR_EACH_IMM_USE_FAST} traverse.
Some useful functions and macros:
@enumerate
@item @code{has_zero_uses (ssa_var)} : Returns true if there are no uses of
@code{ssa_var}.
@item @code{has_single_use (ssa_var)} : Returns true if there is only a
single use of @code{ssa_var}.
@item @code{single_imm_use (ssa_var, use_operand_p *ptr, tree *stmt)} :
Returns true if there is only a single use of @code{ssa_var}, and also returns
the use pointer and statement it occurs in, in the second and third parameters.
@item @code{num_imm_uses (ssa_var)} : Returns the number of immediate uses of
@code{ssa_var}. It is better not to use this if possible since it simply
utilizes a loop to count the uses.
@item @code{PHI_ARG_INDEX_FROM_USE (use_p)} : Given a use within a @code{PHI}
node, return the index number for the use. An assert is triggered if the use
isn't located in a @code{PHI} node.
@item @code{USE_STMT (use_p)} : Return the statement a use occurs in.
@end enumerate
Note that uses are not put into an immediate use list until their statement is
actually inserted into the instruction stream via a @code{bsi_*} routine.
It is also still possible to utilize lazy updating of statements, but this
should be used only when absolutely required. Both alias analysis and the
dominator optimizations currently do this.
When lazy updating is being used, the immediate use information is out of date
and cannot be used reliably. Lazy updating is achieved by simply marking
statements modified via calls to @code{gimple_set_modified} instead of
@code{update_stmt}. When lazy updating is no longer required, all the
modified statements must have @code{update_stmt} called in order to bring them
up to date. This must be done before the optimization is finished, or
@code{verify_ssa} will trigger an abort.
This is done with a simple loop over the instruction stream:
@smallexample
block_stmt_iterator bsi;
basic_block bb;
FOR_EACH_BB (bb)
@{
for (bsi = bsi_start (bb); !bsi_end_p (bsi); bsi_next (&bsi))
update_stmt_if_modified (bsi_stmt (bsi));
@}
@end smallexample
@node SSA
@section Static Single Assignment
@cindex SSA
@cindex static single assignment
Most of the tree optimizers rely on the data flow information provided
by the Static Single Assignment (SSA) form. We implement the SSA form
as described in @cite{R. Cytron, J. Ferrante, B. Rosen, M. Wegman, and
K. Zadeck. Efficiently Computing Static Single Assignment Form and the
Control Dependence Graph. ACM Transactions on Programming Languages
and Systems, 13(4):451-490, October 1991}.
The SSA form is based on the premise that program variables are
assigned in exactly one location in the program. Multiple assignments
to the same variable create new versions of that variable. Naturally,
actual programs are seldom in SSA form initially because variables
tend to be assigned multiple times. The compiler modifies the program
representation so that every time a variable is assigned in the code,
a new version of the variable is created. Different versions of the
same variable are distinguished by subscripting the variable name with
its version number. Variables used in the right-hand side of
expressions are renamed so that their version number matches that of
the most recent assignment.
We represent variable versions using @code{SSA_NAME} nodes. The
renaming process in @file{tree-ssa.cc} wraps every real and
virtual operand with an @code{SSA_NAME} node which contains
the version number and the statement that created the
@code{SSA_NAME}. Only definitions and virtual definitions may
create new @code{SSA_NAME} nodes.
@cindex PHI nodes
Sometimes, flow of control makes it impossible to determine the
most recent version of a variable. In these cases, the compiler
inserts an artificial definition for that variable called
@dfn{PHI function} or @dfn{PHI node}. This new definition merges
all the incoming versions of the variable to create a new name
for it. For instance,
@smallexample
if (@dots{})
a_1 = 5;
else if (@dots{})
a_2 = 2;
else
a_3 = 13;
# a_4 = PHI <a_1, a_2, a_3>
return a_4;
@end smallexample
Since it is not possible to determine which of the three branches
will be taken at runtime, we don't know which of @code{a_1},
@code{a_2} or @code{a_3} to use at the return statement. So, the
SSA renamer creates a new version @code{a_4} which is assigned
the result of ``merging'' @code{a_1}, @code{a_2} and @code{a_3}.
Hence, PHI nodes mean ``one of these operands. I don't know
which''.
The following functions can be used to examine PHI nodes
@defun gimple_phi_result (@var{phi})
Returns the @code{SSA_NAME} created by PHI node @var{phi} (i.e.,
@var{phi}'s LHS)@.
@end defun
@defun gimple_phi_num_args (@var{phi})
Returns the number of arguments in @var{phi}. This number is exactly
the number of incoming edges to the basic block holding @var{phi}@.
@end defun
@defun gimple_phi_arg (@var{phi}, @var{i})
Returns @var{i}th argument of @var{phi}@.
@end defun
@defun gimple_phi_arg_edge (@var{phi}, @var{i})
Returns the incoming edge for the @var{i}th argument of @var{phi}.
@end defun
@defun gimple_phi_arg_def (@var{phi}, @var{i})
Returns the @code{SSA_NAME} for the @var{i}th argument of @var{phi}.
@end defun
@subsection Preserving the SSA form
@findex update_ssa
@cindex preserving SSA form
Some optimization passes make changes to the function that
invalidate the SSA property. This can happen when a pass has
added new symbols or changed the program so that variables that
were previously aliased aren't anymore. Whenever something like this
happens, the affected symbols must be renamed into SSA form again.
Transformations that emit new code or replicate existing statements
will also need to update the SSA form@.
Since GCC implements two different SSA forms for register and virtual
variables, keeping the SSA form up to date depends on whether you are
updating register or virtual names. In both cases, the general idea
behind incremental SSA updates is similar: when new SSA names are
created, they typically are meant to replace other existing names in
the program@.
For instance, given the following code:
@smallexample
1 L0:
2 x_1 = PHI (0, x_5)
3 if (x_1 < 10)
4 if (x_1 > 7)
5 y_2 = 0
6 else
7 y_3 = x_1 + x_7
8 endif
9 x_5 = x_1 + 1
10 goto L0;
11 endif
@end smallexample
Suppose that we insert new names @code{x_10} and @code{x_11} (lines
@code{4} and @code{8})@.
@smallexample
1 L0:
2 x_1 = PHI (0, x_5)
3 if (x_1 < 10)
4 x_10 = @dots{}
5 if (x_1 > 7)
6 y_2 = 0
7 else
8 x_11 = @dots{}
9 y_3 = x_1 + x_7
10 endif
11 x_5 = x_1 + 1
12 goto L0;
13 endif
@end smallexample
We want to replace all the uses of @code{x_1} with the new definitions
of @code{x_10} and @code{x_11}. Note that the only uses that should
be replaced are those at lines @code{5}, @code{9} and @code{11}.
Also, the use of @code{x_7} at line @code{9} should @emph{not} be
replaced (this is why we cannot just mark symbol @code{x} for
renaming)@.
Additionally, we may need to insert a PHI node at line @code{11}
because that is a merge point for @code{x_10} and @code{x_11}. So the
use of @code{x_1} at line @code{11} will be replaced with the new PHI
node. The insertion of PHI nodes is optional. They are not strictly
necessary to preserve the SSA form, and depending on what the caller
inserted, they may not even be useful for the optimizers@.
Updating the SSA form is a two step process. First, the pass has to
identify which names need to be updated and/or which symbols need to
be renamed into SSA form for the first time. When new names are
introduced to replace existing names in the program, the mapping
between the old and the new names are registered by calling
@code{register_new_name_mapping} (note that if your pass creates new
code by duplicating basic blocks, the call to @code{tree_duplicate_bb}
will set up the necessary mappings automatically).
After the replacement mappings have been registered and new symbols
marked for renaming, a call to @code{update_ssa} makes the registered
changes. This can be done with an explicit call or by creating
@code{TODO} flags in the @code{tree_opt_pass} structure for your pass.
There are several @code{TODO} flags that control the behavior of
@code{update_ssa}:
@itemize @bullet
@item @code{TODO_update_ssa}. Update the SSA form inserting PHI nodes
for newly exposed symbols and virtual names marked for updating.
When updating real names, only insert PHI nodes for a real name
@code{O_j} in blocks reached by all the new and old definitions for
@code{O_j}. If the iterated dominance frontier for @code{O_j}
is not pruned, we may end up inserting PHI nodes in blocks that
have one or more edges with no incoming definition for
@code{O_j}. This would lead to uninitialized warnings for
@code{O_j}'s symbol@.
@item @code{TODO_update_ssa_no_phi}. Update the SSA form without
inserting any new PHI nodes at all. This is used by passes that
have either inserted all the PHI nodes themselves or passes that
need only to patch use-def and def-def chains for virtuals
(e.g., DCE)@.
@item @code{TODO_update_ssa_full_phi}. Insert PHI nodes everywhere
they are needed. No pruning of the IDF is done. This is used
by passes that need the PHI nodes for @code{O_j} even if it
means that some arguments will come from the default definition
of @code{O_j}'s symbol (e.g., @code{pass_linear_transform})@.
WARNING: If you need to use this flag, chances are that your
pass may be doing something wrong. Inserting PHI nodes for an
old name where not all edges carry a new replacement may lead to
silent codegen errors or spurious uninitialized warnings@.
@item @code{TODO_update_ssa_only_virtuals}. Passes that update the
SSA form on their own may want to delegate the updating of
virtual names to the generic updater. Since FUD chains are
easier to maintain, this simplifies the work they need to do.
NOTE: If this flag is used, any OLD->NEW mappings for real names
are explicitly destroyed and only the symbols marked for
renaming are processed@.
@end itemize
@subsection Examining @code{SSA_NAME} nodes
@cindex examining SSA_NAMEs
The following macros can be used to examine @code{SSA_NAME} nodes
@defmac SSA_NAME_DEF_STMT (@var{var})
Returns the statement @var{s} that creates the @code{SSA_NAME}
@var{var}. If @var{s} is an empty statement (i.e., @code{IS_EMPTY_STMT
(@var{s})} returns @code{true}), it means that the first reference to
this variable is a USE or a VUSE@.
@end defmac
@defmac SSA_NAME_VERSION (@var{var})
Returns the version number of the @code{SSA_NAME} object @var{var}.
@end defmac
@subsection Walking the dominator tree
@deftypefn {Tree SSA function} void walk_dominator_tree (@var{walk_data}, @var{bb})
This function walks the dominator tree for the current CFG calling a
set of callback functions defined in @var{struct dom_walk_data} in
@file{domwalk.h}. The call back functions you need to define give you
hooks to execute custom code at various points during traversal:
@enumerate
@item Once to initialize any local data needed while processing
@var{bb} and its children. This local data is pushed into an
internal stack which is automatically pushed and popped as the
walker traverses the dominator tree.
@item Once before traversing all the statements in the @var{bb}.
@item Once for every statement inside @var{bb}.
@item Once after traversing all the statements and before recursing
into @var{bb}'s dominator children.
@item It then recurses into all the dominator children of @var{bb}.
@item After recursing into all the dominator children of @var{bb} it
can, optionally, traverse every statement in @var{bb} again
(i.e., repeating steps 2 and 3).
@item Once after walking the statements in @var{bb} and @var{bb}'s
dominator children. At this stage, the block local data stack
is popped.
@end enumerate
@end deftypefn
@node Alias analysis
@section Alias analysis
@cindex alias
@cindex flow-sensitive alias analysis
@cindex flow-insensitive alias analysis
Alias analysis in GIMPLE SSA form consists of two pieces. First
the virtual SSA web ties conflicting memory accesses and provides
a SSA use-def chain and SSA immediate-use chains for walking
possibly dependent memory accesses. Second an alias-oracle can
be queried to disambiguate explicit and implicit memory references.
@enumerate
@item Memory SSA form.
All statements that may use memory have exactly one accompanied use of
a virtual SSA name that represents the state of memory at the
given point in the IL.
All statements that may define memory have exactly one accompanied
definition of a virtual SSA name using the previous state of memory
and defining the new state of memory after the given point in the IL.
@smallexample
int i;
int foo (void)
@{
# .MEM_3 = VDEF <.MEM_2(D)>
i = 1;
# VUSE <.MEM_3>
return i;
@}
@end smallexample
The virtual SSA names in this case are @code{.MEM_2(D)} and
@code{.MEM_3}. The store to the global variable @code{i}
defines @code{.MEM_3} invalidating @code{.MEM_2(D)}. The
load from @code{i} uses that new state @code{.MEM_3}.
The virtual SSA web serves as constraints to SSA optimizers
preventing illegitimate code-motion and optimization. It
also provides a way to walk related memory statements.
@item Points-to and escape analysis.
Points-to analysis builds a set of constraints from the GIMPLE
SSA IL representing all pointer operations and facts we do
or do not know about pointers. Solving this set of constraints
yields a conservatively correct solution for each pointer
variable in the program (though we are only interested in
SSA name pointers) as to what it may possibly point to.
This points-to solution for a given SSA name pointer is stored
in the @code{pt_solution} sub-structure of the
@code{SSA_NAME_PTR_INFO} record. The following accessor
functions are available:
@itemize @bullet
@item @code{pt_solution_includes}
@item @code{pt_solutions_intersect}
@end itemize
Points-to analysis also computes the solution for two special
set of pointers, @code{ESCAPED} and @code{CALLUSED}. Those
represent all memory that has escaped the scope of analysis
or that is used by pure or nested const calls.
@item Type-based alias analysis
Type-based alias analysis is frontend dependent though generic
support is provided by the middle-end in @code{alias.cc}. TBAA
code is used by both tree optimizers and RTL optimizers.
Every language that wishes to perform language-specific alias analysis
should define a function that computes, given a @code{tree}
node, an alias set for the node. Nodes in different alias sets are not
allowed to alias. For an example, see the C front-end function
@code{c_get_alias_set}.
@item Tree alias-oracle
The tree alias-oracle provides means to disambiguate two memory
references and memory references against statements. The following
queries are available:
@itemize @bullet
@item @code{refs_may_alias_p}
@item @code{ref_maybe_used_by_stmt_p}
@item @code{stmt_may_clobber_ref_p}
@end itemize
In addition to those two kind of statement walkers are available
walking statements related to a reference ref.
@code{walk_non_aliased_vuses} walks over dominating memory defining
statements and calls back if the statement does not clobber ref
providing the non-aliased VUSE. The walk stops at
the first clobbering statement or if asked to.
@code{walk_aliased_vdefs} walks over dominating memory defining
statements and calls back on each statement clobbering ref
providing its aliasing VDEF. The walk stops if asked to.
@end enumerate
@node Memory model
@section Memory model
@cindex memory model
The memory model used by the middle-end models that of the C/C++
languages. The middle-end has the notion of an effective type
of a memory region which is used for type-based alias analysis.
The following is a refinement of ISO C99 6.5/6, clarifying the block copy case
to follow common sense and extending the concept of a dynamic effective
type to objects with a declared type as required for C++.
@smallexample
The effective type of an object for an access to its stored value is
the declared type of the object or the effective type determined by
a previous store to it. If a value is stored into an object through
an lvalue having a type that is not a character type, then the
type of the lvalue becomes the effective type of the object for that
access and for subsequent accesses that do not modify the stored value.
If a value is copied into an object using @code{memcpy} or @code{memmove},
or is copied as an array of character type, then the effective type
of the modified object for that access and for subsequent accesses that
do not modify the value is undetermined. For all other accesses to an
object, the effective type of the object is simply the type of the
lvalue used for the access.
@end smallexample

1197
gcc/doc/trouble.texi Normal file
View File

File diff suppressed because it is too large Load Diff

661
gcc/doc/ux.texi Normal file
View File

@ -0,0 +1,661 @@
@c Copyright (C) 2018-2022 Free Software Foundation, Inc.
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node User Experience Guidelines
@chapter User Experience Guidelines
@cindex user experience guidelines
@cindex guidelines, user experience
To borrow a slogan from
@uref{https://elm-lang.org/news/compilers-as-assistants, Elm},
@quotation
@strong{Compilers should be assistants, not adversaries.} A compiler should
not just detect bugs, it should then help you understand why there is a bug.
It should not berate you in a robot voice, it should give you specific hints
that help you write better code. Ultimately, a compiler should make
programming faster and more fun!
@author Evan Czaplicki
@end quotation
This chapter provides guidelines on how to implement diagnostics and
command-line options in ways that we hope achieve the above ideal.
@menu
* Guidelines for Diagnostics:: How to implement diagnostics.
* Guidelines for Options:: Guidelines for command-line options.
@end menu
@node Guidelines for Diagnostics
@section Guidelines for Diagnostics
@cindex guidelines for diagnostics
@cindex diagnostics, guidelines for
@subsection Talk in terms of the user's code
Diagnostics should be worded in terms of the user's source code, and the
source language, rather than GCC's own implementation details.
@subsection Diagnostics are actionable
@cindex diagnostics, actionable
A good diagnostic is @dfn{actionable}: it should assist the user in
taking action.
Consider what an end user will want to do when encountering a diagnostic.
Given an error, an end user will think: ``How do I fix this?''
Given a warning, an end user will think:
@itemize @bullet
@item
``Is this a real problem?''
@item
``Do I care?''
@item
if they decide it's genuine: ``How do I fix this?''
@end itemize
A good diagnostic provides pertinent information to allow the user to
easily answer the above questions.
@subsection The user's attention is important
A perfect compiler would issue a warning on every aspect of the user's
source code that ought to be fixed, and issue no other warnings.
Naturally, this ideal is impossible to achieve.
@cindex signal-to-noise ratio (metaphorical usage for diagnostics)
@cindex diagnostics, false positive
@cindex diagnostics, true positive
@cindex false positive
@cindex true positive
Warnings should have a good @dfn{signal-to-noise ratio}: we should have few
@dfn{false positives} (falsely issuing a warning when no warning is
warranted) and few @dfn{false negatives} (failing to issue a warning when
one @emph{is} justified).
Note that a false positive can mean, in practice, a warning that the
user doesn't agree with. Ideally a diagnostic should contain enough
information to allow the user to make an informed choice about whether
they should care (and how to fix it), but a balance must be drawn against
overloading the user with irrelevant data.
@subsection Sometimes the user didn't write the code
GCC is typically used in two different ways:
@itemize @bullet
@item
Semi-interactive usage: GCC is used as a development tool when the user
is writing code, as the ``compile'' part of the ``edit-compile-debug''
cycle. The user is actively hacking on the code themself (perhaps a
project they wrote, or someone else's), where they just made a change
to the code and want to see what happens, and to be warned about
mistakes.
@item
Batch rebuilds: where the user is recompiling one or more existing
packages, and GCC is a detail that's being invoked by various build
scripts. Examples include a user trying to bring up an operating system
consisting of hundreds of packages on a new CPU architecture, where the
packages were written by many different people, or simply rebuilding
packages after a dependency changed, where the user is hoping
``nothing breaks'', since they are unfamiliar with the code.
@end itemize
Keep both of these styles of usage in mind when implementing diagnostics.
@subsection Precision of Wording
Provide the user with details that allow them to identify what the
problem is. For example, the vaguely-worded message:
@smallexample
demo.c:1:1: warning: 'noinline' attribute ignored [-Wattributes]
1 | int foo __attribute__((noinline));
| ^~~
@end smallexample
@noindent
doesn't tell the user why the attribute was ignored, or what kind of
entity the compiler thought the attribute was being applied to (the
source location for the diagnostic is also poor;
@pxref{input_location_example,,discussion of @code{input_location}}).
A better message would be:
@smallexample
demo.c:1:24: warning: attribute 'noinline' on variable 'foo' was
ignored [-Wattributes]
1 | int foo __attribute__((noinline));
| ~~~ ~~~~~~~~~~~~~~~^~~~~~~~~
demo.c:1:24: note: attribute 'noinline' is only applicable to functions
@end smallexample
@noindent
which spells out the missing information (and fixes the location
information, as discussed below).
The above example uses a note to avoid a combinatorial explosion of possible
messages.
@subsection Try the diagnostic on real-world code
It's worth testing a new warning on many instances of real-world code,
written by different people, and seeing what it complains about, and
what it doesn't complain about.
This may suggest heuristics that silence common false positives.
It may also suggest ways to improve the precision of the message.
@subsection Make mismatches clear
Many diagnostics relate to a mismatch between two different places in the
user's source code. Examples include:
@itemize @bullet
@item
a type mismatch, where the type at a usage site does not match the type
at a declaration
@item
the argument count at a call site does not match the parameter count
at the declaration
@item
something is erroneously duplicated (e.g.@: an error, due to breaking a
uniqueness requirement, or a warning, if it's suggestive of a bug)
@item
an ``opened'' syntactic construct (such as an open-parenthesis) is not
closed
@c TODO: more examples?
@end itemize
In each case, the diagnostic should indicate @strong{both} pertinent
locations (so that the user can easily see the problem and how to fix it).
The standard way to do this is with a note (via @code{inform}). For
example:
@smallexample
auto_diagnostic_group d;
if (warning_at (loc, OPT_Wduplicated_cond,
"duplicated %<if%> condition"))
inform (EXPR_LOCATION (t), "previously used here");
@end smallexample
@noindent
which leads to:
@smallexample
demo.c: In function 'test':
demo.c:5:17: warning: duplicated 'if' condition [-Wduplicated-cond]
5 | else if (flag > 3)
| ~~~~~^~~
demo.c:3:12: note: previously used here
3 | if (flag > 3)
| ~~~~~^~~
@end smallexample
@noindent
The @code{inform} call should be guarded by the return value from the
@code{warning_at} call so that the note isn't emitted when the warning
is suppressed.
For cases involving punctuation where the locations might be near
each other, they can be conditionally consolidated via
@code{gcc_rich_location::add_location_if_nearby}:
@smallexample
auto_diagnostic_group d;
gcc_rich_location richloc (primary_loc);
bool added secondary = richloc.add_location_if_nearby (secondary_loc);
error_at (&richloc, "main message");
if (!added secondary)
inform (secondary_loc, "message for secondary");
@end smallexample
@noindent
This will emit either one diagnostic with two locations:
@smallexample
demo.c:42:10: error: main message
(foo)
~ ^
@end smallexample
@noindent
or two diagnostics:
@smallexample
demo.c:42:4: error: main message
foo)
^
demo.c:40:2: note: message for secondary
(
^
@end smallexample
@subsection Location Information
@cindex diagnostics, locations
@cindex location information
@cindex source code, location information
@cindex caret
GCC's @code{location_t} type can support both ordinary locations,
and locations relating to a macro expansion.
As of GCC 6, ordinary locations changed from supporting just a
point in the user's source code to supporting three points: the
@dfn{caret} location, plus a start and a finish:
@smallexample
a = foo && bar;
~~~~^~~~~~
| | |
| | finish
| caret
start
@end smallexample
Tokens coming out of libcpp have locations of the form @code{caret == start},
such as for @code{foo} here:
@smallexample
a = foo && bar;
^~~
| |
| finish
caret == start
@end smallexample
Compound expressions should be reported using the location of the
expression as a whole, rather than just of one token within it.
For example, in @code{-Wformat}, rather than underlining just the first
token of a bad argument:
@smallexample
printf("hello %i %s", (long)0, "world");
~^ ~
%li
@end smallexample
@noindent
the whole of the expression should be underlined, so that the user can
easily identify what is being referred to:
@smallexample
printf("hello %i %s", (long)0, "world");
~^ ~~~~~~~
%li
@end smallexample
@c this was r251239
Avoid using the @code{input_location} global, and the diagnostic functions
that implicitly use it---use @code{error_at} and @code{warning_at} rather
than @code{error} and @code{warning}, and provide the most appropriate
@code{location_t} value available at that phase of the compilation. It's
possible to supply secondary @code{location_t} values via
@code{rich_location}.
@noindent
@anchor{input_location_example}
For example, in the example of imprecise wording above, generating the
diagnostic using @code{warning}:
@smallexample
// BAD: implicitly uses @code{input_location}
warning (OPT_Wattributes, "%qE attribute ignored", name);
@end smallexample
@noindent
leads to:
@smallexample
// BAD: uses @code{input_location}
demo.c:1:1: warning: 'noinline' attribute ignored [-Wattributes]
1 | int foo __attribute__((noinline));
| ^~~
@end smallexample
@noindent
which thus happened to use the location of the @code{int} token, rather
than that of the attribute. Using @code{warning_at} with the location of
the attribute, providing the location of the declaration in question
as a secondary location, and adding a note:
@smallexample
auto_diagnostic_group d;
gcc_rich_location richloc (attrib_loc);
richloc.add_range (decl_loc);
if (warning_at (OPT_Wattributes, &richloc,
"attribute %qE on variable %qE was ignored", name))
inform (attrib_loc, "attribute %qE is only applicable to functions");
@end smallexample
@noindent
would lead to:
@smallexample
// OK: use location of attribute, with a secondary location
demo.c:1:24: warning: attribute 'noinline' on variable 'foo' was
ignored [-Wattributes]
1 | int foo __attribute__((noinline));
| ~~~ ~~~~~~~~~~~~~~~^~~~~~~~~
demo.c:1:24: note: attribute 'noinline' is only applicable to functions
@end smallexample
@c TODO labelling of ranges
@subsection Coding Conventions
See the @uref{https://gcc.gnu.org/codingconventions.html#Diagnostics,
diagnostics section} of the GCC coding conventions.
In the C++ front end, when comparing two types in a message, use @samp{%H}
and @samp{%I} rather than @samp{%T}, as this allows the diagnostics
subsystem to highlight differences between template-based types.
For example, rather than using @samp{%qT}:
@smallexample
// BAD: a pair of %qT used in C++ front end for type comparison
error_at (loc, "could not convert %qE from %qT to %qT", expr,
TREE_TYPE (expr), type);
@end smallexample
@noindent
which could lead to:
@smallexample
error: could not convert 'map<int, double>()' from 'map<int,double>'
to 'map<int,int>'
@end smallexample
@noindent
using @samp{%H} and @samp{%I} (via @samp{%qH} and @samp{%qI}):
@smallexample
// OK: compare types in C++ front end via %qH and %qI
error_at (loc, "could not convert %qE from %qH to %qI", expr,
TREE_TYPE (expr), type);
@end smallexample
@noindent
allows the above output to be simplified to:
@smallexample
error: could not convert 'map<int, double>()' from 'map<[...],double>'
to 'map<[...],int>'
@end smallexample
@noindent
where the @code{double} and @code{int} are colorized to highlight them.
@c %H and %I were added in r248698.
@subsection Group logically-related diagnostics
Use @code{auto_diagnostic_group} when issuing multiple related
diagnostics (seen in various examples on this page). This informs the
diagnostic subsystem that all diagnostics issued within the lifetime
of the @code{auto_diagnostic_group} are related. For example,
@option{-fdiagnostics-format=json} will treat the first diagnostic
emitted within the group as a top-level diagnostic, and all subsequent
diagnostics within the group as its children.
@subsection Quoting
Text should be quoted by either using the @samp{q} modifier in a directive
such as @samp{%qE}, or by enclosing the quoted text in a pair of @samp{%<}
and @samp{%>} directives, and never by using explicit quote characters.
The directives handle the appropriate quote characters for each language
and apply the correct color or highlighting.
The following elements should be quoted in GCC diagnostics:
@itemize @bullet
@item
Language keywords.
@item
Tokens.
@item
Boolean, numerical, character, and string constants that appear in the
source code.
@item
Identifiers, including function, macro, type, and variable names.
@end itemize
Other elements such as numbers that do not refer to numeric constants that
appear in the source code should not be quoted. For example, in the message:
@smallexample
argument %d of %qE must be a pointer type
@end smallexample
@noindent
since the argument number does not refer to a numerical constant in the
source code it should not be quoted.
@subsection Spelling and Terminology
See the @uref{https://gcc.gnu.org/codingconventions.html#Spelling
Spelling, terminology and markup} section of the GCC coding conventions.
@subsection Fix-it hints
@cindex fix-it hints
@cindex diagnostics guidelines, fix-it hints
GCC's diagnostic subsystem can emit @dfn{fix-it hints}: small suggested
edits to the user's source code.
They are printed by default underneath the code in question. They
can also be viewed via @option{-fdiagnostics-generate-patch} and
@option{-fdiagnostics-parseable-fixits}. With the latter, an IDE
ought to be able to offer to automatically apply the suggested fix.
Fix-it hints contain code fragments, and thus they should not be marked
for translation.
Fix-it hints can be added to a diagnostic by using a @code{rich_location}
rather than a @code{location_t} - the fix-it hints are added to the
@code{rich_location} using one of the various @code{add_fixit} member
functions of @code{rich_location}. They are documented with
@code{rich_location} in @file{libcpp/line-map.h}.
It's easiest to use the @code{gcc_rich_location} subclass of
@code{rich_location} found in @file{gcc-rich-location.h}, as this
implicitly supplies the @code{line_table} variable.
For example:
@smallexample
if (const char *suggestion = hint.suggestion ())
@{
gcc_rich_location richloc (location);
richloc.add_fixit_replace (suggestion);
error_at (&richloc,
"%qE does not name a type; did you mean %qs?",
id, suggestion);
@}
@end smallexample
@noindent
which can lead to:
@smallexample
spellcheck-typenames.C:73:1: error: 'singed' does not name a type; did
you mean 'signed'?
73 | singed char ch;
| ^~~~~~
| signed
@end smallexample
Non-trivial edits can be built up by adding multiple fix-it hints to one
@code{rich_location}. It's best to express the edits in terms of the
locations of individual tokens. Various handy functions for adding
fix-it hints for idiomatic C and C++ can be seen in
@file{gcc-rich-location.h}.
@subsubsection Fix-it hints should work
When implementing a fix-it hint, please verify that the suggested edit
leads to fixed, compilable code. (Unfortunately, this currently must be
done by hand using @option{-fdiagnostics-generate-patch}. It would be
good to have an automated way of verifying that fix-it hints actually fix
the code).
For example, a ``gotcha'' here is to forget to add a space when adding a
missing reserved word. Consider a C++ fix-it hint that adds
@code{typename} in front of a template declaration. A naive way to
implement this might be:
@smallexample
gcc_rich_location richloc (loc);
// BAD: insertion is missing a trailing space
richloc.add_fixit_insert_before ("typename");
error_at (&richloc, "need %<typename%> before %<%T::%E%> because "
"%qT is a dependent scope",
parser->scope, id, parser->scope);
@end smallexample
@noindent
When applied to the code, this might lead to:
@smallexample
T::type x;
@end smallexample
@noindent
being ``corrected'' to:
@smallexample
typenameT::type x;
@end smallexample
@noindent
In this case, the correct thing to do is to add a trailing space after
@code{typename}:
@smallexample
gcc_rich_location richloc (loc);
// OK: note that here we have a trailing space
richloc.add_fixit_insert_before ("typename ");
error_at (&richloc, "need %<typename%> before %<%T::%E%> because "
"%qT is a dependent scope",
parser->scope, id, parser->scope);
@end smallexample
@noindent
leading to this corrected code:
@smallexample
typename T::type x;
@end smallexample
@subsubsection Express deletion in terms of deletion, not replacement
It's best to express deletion suggestions in terms of deletion fix-it
hints, rather than replacement fix-it hints. For example, consider this:
@smallexample
auto_diagnostic_group d;
gcc_rich_location richloc (location_of (retval));
tree name = DECL_NAME (arg);
richloc.add_fixit_replace (IDENTIFIER_POINTER (name));
warning_at (&richloc, OPT_Wredundant_move,
"redundant move in return statement");
@end smallexample
@noindent
which is intended to e.g.@: replace a @code{std::move} with the underlying
value:
@smallexample
return std::move (retval);
~~~~~~~~~~^~~~~~~~
retval
@end smallexample
@noindent
where the change has been expressed as replacement, replacing
with the name of the declaration.
This works for simple cases, but consider this case:
@smallexample
#ifdef SOME_CONFIG_FLAG
# define CONFIGURY_GLOBAL global_a
#else
# define CONFIGURY_GLOBAL global_b
#endif
int fn ()
@{
return std::move (CONFIGURY_GLOBAL /* some comment */);
@}
@end smallexample
@noindent
The above implementation erroneously strips out the macro and the
comment in the fix-it hint:
@smallexample
return std::move (CONFIGURY_GLOBAL /* some comment */);
~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
global_a
@end smallexample
@noindent
and thus this resulting code:
@smallexample
return global_a;
@end smallexample
@noindent
It's better to do deletions in terms of deletions; deleting the
@code{std::move (} and the trailing close-paren, leading to
this:
@smallexample
return std::move (CONFIGURY_GLOBAL /* some comment */);
~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
CONFIGURY_GLOBAL /* some comment */
@end smallexample
@noindent
and thus this result:
@smallexample
return CONFIGURY_GLOBAL /* some comment */;
@end smallexample
@noindent
Unfortunately, the pertinent @code{location_t} values are not always
available.
@c the above was https://gcc.gnu.org/ml/gcc-patches/2018-08/msg01474.html
@subsubsection Multiple suggestions
In the rare cases where you need to suggest more than one mutually
exclusive solution to a problem, this can be done by emitting
multiple notes and calling
@code{rich_location::fixits_cannot_be_auto_applied} on each note's
@code{rich_location}. If this is called, then the fix-it hints in
the @code{rich_location} will be printed, but will not be added to
generated patches.
@node Guidelines for Options
@section Guidelines for Options
@cindex command-line options, guidelines for
@cindex options, guidelines for
@cindex guidelines for options
@c TODO

968
gcc/fortran/gfc-internals.texi Normal file
View File

@ -0,0 +1,968 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename gfc-internals.info
@set copyrights-gfortran 2007-2022
@include gcc-common.texi
@synindex tp cp
@settitle GNU Fortran Compiler Internals
@c %**end of header
@c Use with @@smallbook.
@c %** start of document
@c Cause even numbered pages to be printed on the left hand side of
@c the page and odd numbered pages to be printed on the right hand
@c side of the page. Using this, you can print on both sides of a
@c sheet of paper and have the text on the same part of the sheet.
@c The text on right hand pages is pushed towards the right hand
@c margin and the text on left hand pages is pushed toward the left
@c hand margin.
@c (To provide the reverse effect, set bindingoffset to -0.75in.)
@c @tex
@c \global\bindingoffset=0.75in
@c \global\normaloffset =0.75in
@c @end tex
@copying
Copyright @copyright{} @value{copyrights-gfortran} 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.
@end copying
@ifinfo
@dircategory Software development
@direntry
* gfortran: (gfortran). The GNU Fortran Compiler.
@end direntry
This file documents the internals of the GNU Fortran
compiler, (@command{gfortran}).
Published by the Free Software Foundation
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301 USA
@insertcopying
@end ifinfo
@setchapternewpage odd
@titlepage
@title GNU Fortran Internals
@versionsubtitle
@author The @t{gfortran} team
@page
@vskip 0pt plus 1filll
Published by the Free Software Foundation@*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301, USA@*
@c Last printed ??ber, 19??.@*
@c Printed copies are available for $? each.@*
@c ISBN ???
@sp 1
@insertcopying
@end titlepage
@summarycontents
@contents
@page
@c ---------------------------------------------------------------------
@c TexInfo table of contents.
@c ---------------------------------------------------------------------
@ifnottex
@node Top
@top Introduction
@cindex Introduction
This manual documents the internals of @command{gfortran},
the GNU Fortran compiler.
@ifset DEVELOPMENT
@emph{Warning:} This document, and the compiler it describes, are still
under development. While efforts are made to keep it up-to-date, it might
not accurately reflect the status of the most recent GNU Fortran compiler.
@end ifset
@comment
@comment When you add a new menu item, please keep the right hand
@comment aligned to the same column. Do not use tabs. This provides
@comment better formatting.
@comment
@menu
* Introduction:: About this manual.
* User Interface:: Code that Interacts with the User.
* Frontend Data Structures::
Data structures used by the frontend
* Object Orientation:: Internals of Fortran 2003 OOP features.
* Translating to GENERIC::
Generating the intermediate language for later stages.
* LibGFortran:: The LibGFortran Runtime Library.
* GNU Free Documentation License::
How you can copy and share this manual.
* Index:: Index of this documentation.
@end menu
@end ifnottex
@c ---------------------------------------------------------------------
@c Introduction
@c ---------------------------------------------------------------------
@node Introduction
@chapter Introduction
@c The following duplicates the text on the TexInfo table of contents.
@iftex
This manual documents the internals of @command{gfortran}, the GNU Fortran
compiler.
@ifset DEVELOPMENT
@emph{Warning:} This document, and the compiler it describes, are still
under development. While efforts are made to keep it up-to-date, it
might not accurately reflect the status of the most recent GNU Fortran
compiler.
@end ifset
@end iftex
At present, this manual is very much a work in progress, containing
miscellaneous notes about the internals of the compiler. It is hoped
that at some point in the future it will become a reasonably complete
guide; in the interim, GNU Fortran developers are strongly encouraged to
contribute to it as a way of keeping notes while working on the
compiler.
@c ---------------------------------------------------------------------
@c Code that Interacts with the User
@c ---------------------------------------------------------------------
@node User Interface
@chapter Code that Interacts with the User
@menu
* Command-Line Options:: Command-Line Options.
* Error Handling:: Error Handling.
@end menu
@c ---------------------------------------------------------------------
@c Command-Line Options
@c ---------------------------------------------------------------------
@node Command-Line Options
@section Command-Line Options
Command-line options for @command{gfortran} involve four interrelated
pieces within the Fortran compiler code.
The relevant command-line flag is defined in @file{lang.opt}, according
to the documentation in @ref{Options,, Options, gccint, GNU Compiler
Collection Internals}. This is then processed by the overall GCC
machinery to create the code that enables @command{gfortran} and
@command{gcc} to recognize the option in the command-line arguments and
call the relevant handler function.
This generated code calls the @code{gfc_handle_option} code in
@file{options.cc} with an enumerator variable indicating which option is
to be processed, and the relevant integer or string values associated
with that option flag. Typically, @code{gfc_handle_option} uses these
arguments to set global flags which record the option states.
The global flags that record the option states are stored in the
@code{gfc_option_t} struct, which is defined in @file{gfortran.h}.
Before the options are processed, initial values for these flags are set
in @code{gfc_init_option} in @file{options.cc}; these become the default
values for the options.
@c ---------------------------------------------------------------------
@c Error Handling
@c ---------------------------------------------------------------------
@node Error Handling
@section Error Handling
The GNU Fortran compiler's parser operates by testing each piece of
source code against a variety of matchers. In some cases, if these
matchers do not match the source code, they will store an error message
in a buffer. If the parser later finds a matcher that does correctly
match the source code, then the buffered error is discarded. However,
if the parser cannot find a match, then the buffered error message is
reported to the user. This enables the compiler to provide more
meaningful error messages even in the many cases where (erroneous)
Fortran syntax is ambiguous due to things like the absence of reserved
keywords.
As an example of how this works, consider the following line:
@smallexample
IF = 3
@end smallexample
Hypothetically, this may get passed to the matcher for an @code{IF}
statement. Since this could plausibly be an erroneous @code{IF}
statement, the matcher will buffer an error message reporting the
absence of an expected @samp{(} following an @code{IF}. Since no
matchers reported an error-free match, however, the parser will also try
matching this against a variable assignment. When @code{IF} is a valid
variable, this will be parsed as an assignment statement, and the error
discarded. However, when @code{IF} is not a valid variable, this
buffered error message will be reported to the user.
The error handling code is implemented in @file{error.cc}. Errors are
normally entered into the buffer with the @code{gfc_error} function.
Warnings go through a similar buffering process, and are entered into
the buffer with @code{gfc_warning}. There is also a special-purpose
function, @code{gfc_notify_std}, for things which have an error/warning
status that depends on the currently-selected language standard.
The @code{gfc_error_check} function checks the buffer for errors,
reports the error message to the user if one exists, clears the buffer,
and returns a flag to the user indicating whether or not an error
existed. To check the state of the buffer without changing its state or
reporting the errors, the @code{gfc_error_flag_test} function can be
used. The @code{gfc_clear_error} function will clear out any errors in
the buffer, without reporting them. The @code{gfc_warning_check} and
@code{gfc_clear_warning} functions provide equivalent functionality for
the warning buffer.
Only one error and one warning can be in the buffers at a time, and
buffering another will overwrite the existing one. In cases where one
may wish to work on a smaller piece of source code without disturbing an
existing error state, the @code{gfc_push_error}, @code{gfc_pop_error},
and @code{gfc_free_error} mechanism exists to implement a stack for the
error buffer.
For cases where an error or warning should be reported immediately
rather than buffered, the @code{gfc_error_now} and
@code{gfc_warning_now} functions can be used. Normally, the compiler
will continue attempting to parse the program after an error has
occurred, but if this is not appropriate, the @code{gfc_fatal_error}
function should be used instead. For errors that are always the result
of a bug somewhere in the compiler, the @code{gfc_internal_error}
function should be used.
The syntax for the strings used to produce the error/warning message in
the various error and warning functions is similar to the @code{printf}
syntax, with @samp{%}-escapes to insert variable values. The details,
and the allowable codes, are documented in the @code{error_print}
function in @file{error.cc}.
@c ---------------------------------------------------------------------
@c Frontend Data Structures
@c ---------------------------------------------------------------------
@node Frontend Data Structures
@chapter Frontend Data Structures
@cindex data structures
This chapter should describe the details necessary to understand how
the various @code{gfc_*} data are used and interact. In general it is
advisable to read the code in @file{dump-parse-tree.cc} as its routines
should exhaust all possible valid combinations of content for these
structures.
@menu
* gfc_code:: Representation of Executable Statements.
* gfc_expr:: Representation of Values and Expressions.
@end menu
@c gfc_code
@c --------
@node gfc_code
@section @code{gfc_code}
@cindex statement chaining
@tindex @code{gfc_code}
@tindex @code{struct gfc_code}
The executable statements in a program unit are represented by a
nested chain of @code{gfc_code} structures. The type of statement is
identified by the @code{op} member of the structure, the different
possible values are enumerated in @code{gfc_exec_op}. A special
member of this @code{enum} is @code{EXEC_NOP} which is used to
represent the various @code{END} statements if they carry a label.
Depending on the type of statement some of the other fields will be
filled in. Fields that are generally applicable are the @code{next}
and @code{here} fields. The former points to the next statement in
the current block or is @code{NULL} if the current statement is the
last in a block, @code{here} points to the statement label of the
current statement.
If the current statement is one of @code{IF}, @code{DO}, @code{SELECT}
it starts a block, i.e.@: a nested level in the program. In order to
represent this, the @code{block} member is set to point to a
@code{gfc_code} structure whose @code{next} member starts the chain of
statements inside the block; this structure's @code{op} member should be set to
the same value as the parent structure's @code{op} member. The @code{SELECT}
and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF}
and @code{ELSE} blocks or the various @code{CASE}s, respectively). These chains
are linked-lists formed by the @code{block} members.
Consider the following example code:
@example
IF (foo < 20) THEN
PRINT *, "Too small"
foo = 20
ELSEIF (foo > 50) THEN
PRINT *, "Too large"
foo = 50
ELSE
PRINT *, "Good"
END IF
@end example
This statement-block will be represented in the internal gfortran tree as
follows, were the horizontal link-chains are those induced by the @code{next}
members and vertical links down are those of @code{block}. @samp{==|} and
@samp{--|} mean @code{NULL} pointers to mark the end of a chain:
@example
... ==> IF ==> ...
|
+--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==|
|
+--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==|
|
+--> ELSE ==> PRINT *, "Good" ==|
|
+--|
@end example
@subsection IF Blocks
Conditionals are represented by @code{gfc_code} structures with their
@code{op} member set to @code{EXEC_IF}. This structure's @code{block}
member must point to another @code{gfc_code} node that is the header of the
if-block. This header's @code{op} member must be set to @code{EXEC_IF}, too,
its @code{expr} member holds the condition to check for, and its @code{next}
should point to the code-chain of the statements to execute if the condition is
true.
If in addition an @code{ELSEIF} or @code{ELSE} block is present, the
@code{block} member of the if-block-header node points to yet another
@code{gfc_code} structure that is the header of the elseif- or else-block. Its
structure is identical to that of the if-block-header, except that in case of an
@code{ELSE} block without a new condition the @code{expr} member should be
@code{NULL}. This block can itself have its @code{block} member point to the
next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.
@subsection Loops
@code{DO} loops are stored in the tree as @code{gfc_code} nodes with their
@code{op} set to @code{EXEC_DO} for a @code{DO} loop with iterator variable and
to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks.
Their @code{block} member should point to a @code{gfc_code} structure heading
the code-chain of the loop body; its @code{op} member should be set to
@code{EXEC_DO} or @code{EXEC_DO_WHILE}, too, respectively.
For @code{DO WHILE} loops, the loop condition is stored on the top
@code{gfc_code} structure's @code{expr} member; @code{DO} forever loops are
simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in
the internal representation.
Similarly, @code{DO} loops with an iterator have instead of the condition their
@code{ext.iterator} member set to the correct values for the loop iterator
variable and its range.
@subsection @code{SELECT} Statements
A @code{SELECT} block is introduced by a @code{gfc_code} structure with an
@code{op} member of @code{EXEC_SELECT} and @code{expr} containing the expression
to evaluate and test. Its @code{block} member starts a list of @code{gfc_code}
structures linked together by their @code{block} members that stores the various
@code{CASE} parts.
Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too,
its @code{next} member points to the code-chain to be executed in the current
case-block, and @code{extx.case_list} contains the case-values this block
corresponds to. The @code{block} member links to the next case in the list.
@subsection @code{BLOCK} and @code{ASSOCIATE}
The code related to a @code{BLOCK} statement is stored inside an
@code{gfc_code} structure (say @var{c})
with @code{c.op} set to @code{EXEC_BLOCK}. The
@code{gfc_namespace} holding the locally defined variables of the
@code{BLOCK} is stored in @code{c.ext.block.ns}. The code inside the
construct is in @code{c.code}.
@code{ASSOCIATE} constructs are based on @code{BLOCK} and thus also have
the internal storage structure described above (including @code{EXEC_BLOCK}).
However, for them @code{c.ext.block.assoc} is set additionally and points
to a linked list of @code{gfc_association_list} structures. Those
structures basically store a link of associate-names to target expressions.
The associate-names themselves are still also added to the @code{BLOCK}'s
namespace as ordinary symbols, but they have their @code{gfc_symbol}'s
member @code{assoc} set also pointing to the association-list structure.
This way associate-names can be distinguished from ordinary variables
and their target expressions identified.
For association to expressions (as opposed to variables), at the very beginning
of the @code{BLOCK} construct assignments are automatically generated to
set the corresponding variables to their target expressions' values, and
later on the compiler simply disallows using such associate-names in contexts
that may change the value.
@c gfc_expr
@c --------
@node gfc_expr
@section @code{gfc_expr}
@tindex @code{gfc_expr}
@tindex @code{struct gfc_expr}
Expressions and ``values'', including constants, variable-, array- and
component-references as well as complex expressions consisting of operators and
function calls are internally represented as one or a whole tree of
@code{gfc_expr} objects. The member @code{expr_type} specifies the overall
type of an expression (for instance, @code{EXPR_CONSTANT} for constants or
@code{EXPR_VARIABLE} for variable references). The members @code{ts} and
@code{rank} as well as @code{shape}, which can be @code{NULL}, specify
the type, rank and, if applicable, shape of the whole expression or expression
tree of which the current structure is the root. @code{where} is the locus of
this expression in the source code.
Depending on the flavor of the expression being described by the object
(that is, the value of its @code{expr_type} member), the corresponding structure
in the @code{value} union will usually contain additional data describing the
expression's value in a type-specific manner. The @code{ref} member is used to
build chains of (array-, component- and substring-) references if the expression
in question contains such references, see below for details.
@subsection Constants
Scalar constants are represented by @code{gfc_expr} nodes with their
@code{expr_type} set to @code{EXPR_CONSTANT}. The constant's value shall
already be known at compile-time and is stored in the @code{logical},
@code{integer}, @code{real}, @code{complex} or @code{character} struct inside
@code{value}, depending on the constant's type specification.
@subsection Operators
Operator-expressions are expressions that are the result of the execution of
some operator on one or two operands. The expressions have an @code{expr_type}
of @code{EXPR_OP}. Their @code{value.op} structure contains additional data.
@code{op1} and optionally @code{op2} if the operator is binary point to the
two operands, and @code{operator} or @code{uop} describe the operator that
should be evaluated on these operands, where @code{uop} describes a user-defined
operator.
@subsection Function Calls
If the expression is the return value of a function-call, its @code{expr_type}
is set to @code{EXPR_FUNCTION}, and @code{symtree} must point to the symtree
identifying the function to be called. @code{value.function.actual} holds the
actual arguments given to the function as a linked list of
@code{gfc_actual_arglist} nodes.
The other members of @code{value.function} describe the function being called
in more detail, containing a link to the intrinsic symbol or user-defined
function symbol if the call is to an intrinsic or external function,
respectively. These values are determined during resolution-phase from the
structure's @code{symtree} member.
A special case of function calls are ``component calls'' to type-bound
procedures; those have the @code{expr_type} @code{EXPR_COMPCALL} with
@code{value.compcall} containing the argument list and the procedure called,
while @code{symtree} and @code{ref} describe the object on which the procedure
was called in the same way as a @code{EXPR_VARIABLE} expression would.
@xref{Type-bound Procedures}.
@subsection Array- and Structure-Constructors
Array- and structure-constructors (one could probably call them ``array-'' and
``derived-type constants'') are @code{gfc_expr} structures with their
@code{expr_type} member set to @code{EXPR_ARRAY} or @code{EXPR_STRUCTURE},
respectively. For structure constructors, @code{symtree} points to the
derived-type symbol for the type being constructed.
The values for initializing each array element or structure component are
stored as linked-list of @code{gfc_constructor} nodes in the
@code{value.constructor} member.
@subsection Null
@code{NULL} is a special value for pointers; it can be of different base types.
Such a @code{NULL} value is represented in the internal tree by a
@code{gfc_expr} node with @code{expr_type} @code{EXPR_NULL}. If the base type
of the @code{NULL} expression is known, it is stored in @code{ts} (that's for
instance the case for default-initializers of @code{ALLOCATABLE} components),
but this member can also be set to @code{BT_UNKNOWN} if the information is not
available (for instance, when the expression is a pointer-initializer
@code{NULL()}).
@subsection Variables and Reference Expressions
Variable references are @code{gfc_expr} structures with their @code{expr_type}
set to @code{EXPR_VARIABLE}; their @code{symtree} should point to the variable
that is referenced.
For this type of expression, it's also possible to chain array-, component-
or substring-references to the original expression to get something like
@samp{struct%component(2:5)}, where @code{component} is either an array or
a @code{CHARACTER} member of @code{struct} that is of some derived-type. Such a
chain of references is achieved by a linked list headed by @code{ref} of the
@code{gfc_expr} node. For the example above it would be (@samp{==|} is the
last @code{NULL} pointer):
@smallexample
EXPR_VARIABLE(struct) ==> REF_COMPONENT(component) ==> REF_ARRAY(2:5) ==|
@end smallexample
If @code{component} is a string rather than an array, the last element would be
a @code{REF_SUBSTRING} reference, of course. If the variable itself or some
component referenced is an array and the expression should reference the whole
array rather than being followed by an array-element or -section reference, a
@code{REF_ARRAY} reference must be built as the last element in the chain with
an array-reference type of @code{AR_FULL}. Consider this example code:
@smallexample
TYPE :: mytype
INTEGER :: array(42)
END TYPE mytype
TYPE(mytype) :: variable
INTEGER :: local_array(5)
CALL do_something (variable%array, local_array)
@end smallexample
The @code{gfc_expr} nodes representing the arguments to the @samp{do_something}
call will have a reference-chain like this:
@smallexample
EXPR_VARIABLE(variable) ==> REF_COMPONENT(array) ==> REF_ARRAY(FULL) ==|
EXPR_VARIABLE(local_array) ==> REF_ARRAY(FULL) ==|
@end smallexample
@subsection Constant Substring References
@code{EXPR_SUBSTRING} is a special type of expression that encodes a substring
reference of a constant string, as in the following code snippet:
@smallexample
x = "abcde"(1:2)
@end smallexample
In this case, @code{value.character} contains the full string's data as if it
was a string constant, but the @code{ref} member is also set and points to a
substring reference as described in the subsection above.
@c ---------------------------------------------------------------------
@c F2003 OOP
@c ---------------------------------------------------------------------
@node Object Orientation
@chapter Internals of Fortran 2003 OOP Features
@menu
* Type-bound Procedures:: Type-bound procedures.
* Type-bound Operators:: Type-bound operators.
@end menu
@c Type-bound procedures
@c ---------------------
@node Type-bound Procedures
@section Type-bound Procedures
Type-bound procedures are stored in the @code{tb_sym_root} of the namespace
@code{f2k_derived} associated with the derived-type symbol as @code{gfc_symtree}
nodes. The name and symbol of these symtrees corresponds to the binding-name
of the procedure, i.e. the name that is used to call it from the context of an
object of the derived-type.
In addition, this type of symtrees stores in @code{n.tb} a struct of type
@code{gfc_typebound_proc} containing the additional data needed: The
binding attributes (like @code{PASS} and @code{NOPASS}, @code{NON_OVERRIDABLE}
or the access-specifier), the binding's target(s) and, if the current binding
overrides or extends an inherited binding of the same name, @code{overridden}
points to this binding's @code{gfc_typebound_proc} structure.
@subsection Specific Bindings
@c --------------------------
For specific bindings (declared with @code{PROCEDURE}), if they have a
passed-object argument, the passed-object dummy argument is first saved by its
name, and later during resolution phase the corresponding argument is looked for
and its position remembered as @code{pass_arg_num} in @code{gfc_typebound_proc}.
The binding's target procedure is pointed-to by @code{u.specific}.
@code{DEFERRED} bindings are just like ordinary specific bindings, except
that their @code{deferred} flag is set of course and that @code{u.specific}
points to their ``interface'' defining symbol (might be an abstract interface)
instead of the target procedure.
At the moment, all type-bound procedure calls are statically dispatched and
transformed into ordinary procedure calls at resolution time; their actual
argument list is updated to include at the right position the passed-object
argument, if applicable, and then a simple procedure call to the binding's
target procedure is built. To handle dynamic dispatch in the future, this will
be extended to allow special code generation during the trans-phase to dispatch
based on the object's dynamic type.
@subsection Generic Bindings
@c -------------------------
Bindings declared as @code{GENERIC} store the specific bindings they target as
a linked list using nodes of type @code{gfc_tbp_generic} in @code{u.generic}.
For each specific target, the parser records its symtree and during resolution
this symtree is bound to the corresponding @code{gfc_typebound_proc} structure
of the specific target.
Calls to generic bindings are handled entirely in the resolution-phase, where
for the actual argument list present the matching specific binding is found
and the call's target procedure (@code{value.compcall.tbp}) is re-pointed to
the found specific binding and this call is subsequently handled by the logic
for specific binding calls.
@subsection Calls to Type-bound Procedures
@c ---------------------------------------
Calls to type-bound procedures are stored in the parse-tree as @code{gfc_expr}
nodes of type @code{EXPR_COMPCALL}. Their @code{value.compcall.actual} saves
the actual argument list of the call and @code{value.compcall.tbp} points to the
@code{gfc_typebound_proc} structure of the binding to be called. The object
in whose context the procedure was called is saved by combination of
@code{symtree} and @code{ref}, as if the expression was of type
@code{EXPR_VARIABLE}.
For code like this:
@smallexample
CALL myobj%procedure (arg1, arg2)
@end smallexample
@noindent
the @code{CALL} is represented in the parse-tree as a @code{gfc_code} node of
type @code{EXEC_COMPCALL}. The @code{expr} member of this node holds an
expression of type @code{EXPR_COMPCALL} of the same structure as mentioned above
except that its target procedure is of course a @code{SUBROUTINE} and not a
@code{FUNCTION}.
Expressions that are generated internally (as expansion of a type-bound
operator call) may also use additional flags and members.
@code{value.compcall.ignore_pass} signals that even though a @code{PASS}
attribute may be present the actual argument list should not be updated because
it already contains the passed-object.
@code{value.compcall.base_object} overrides, if it is set, the base-object
(that is normally stored in @code{symtree} and @code{ref} as mentioned above);
this is needed because type-bound operators can be called on a base-object that
need not be of type @code{EXPR_VARIABLE} and thus representable in this way.
Finally, if @code{value.compcall.assign} is set, the call was produced in
expansion of a type-bound assignment; this means that proper dependency-checking
needs to be done when relevant.
@c Type-bound operators
@c --------------------
@node Type-bound Operators
@section Type-bound Operators
Type-bound operators are in fact basically just @code{GENERIC} procedure
bindings and are represented much in the same way as those (see
@ref{Type-bound Procedures}).
They come in two flavours:
User-defined operators (like @code{.MYOPERATOR.})
are stored in the @code{f2k_derived} namespace's @code{tb_uop_root}
symtree exactly like ordinary type-bound procedures are stored in
@code{tb_sym_root}; their symtrees' names are the operator-names (e.g.
@samp{myoperator} in the example).
Intrinsic operators on the other hand are stored in the namespace's
array member @code{tb_op} indexed by the intrinsic operator's enum
value. Those need not be packed into @code{gfc_symtree} structures and are
only @code{gfc_typebound_proc} instances.
When an operator call or assignment is found that cannot be handled in
another way (i.e. neither matches an intrinsic nor interface operator
definition) but that contains a derived-type expression, all type-bound
operators defined on that derived-type are checked for a match with
the operator call. If there's indeed a relevant definition, the
operator call is replaced with an internally generated @code{GENERIC}
type-bound procedure call to the respective definition and that call is
further processed.
@c ---------------------------------------------------------------------
@c - Translating to GENERIC
@c ---------------------------------------------------------------------
@node Translating to GENERIC
@chapter Generating the intermediate language for later stages.
This chapter deals with the transformation of gfortran's frontend data
structures to the intermediate language used by the later stages of
the compiler, the so-called middle end.
Data structures relating to this are found in the source files
@file{trans*.h} and @file{trans-*.c}.
@menu
* Basic Data Structures:: Basic data structures.
* Converting Expressions:: Converting expressions to tree.
* Translating Statements:: Translating statements.
* Accessing Declarations:: Accessing declarations.
@end menu
@node Basic Data Structures
@section Basic data structures
Gfortran creates GENERIC as an intermediate language for the
middle-end. Details about GENERIC can be found in the GCC manual.
The basic data structure of GENERIC is a @code{tree}. Everything in
GENERIC is a @code{tree}, including types and statements. Fortunately
for the gfortran programmer, @code{tree} variables are
garbage-collected, so doing memory management for them is not
necessary.
@code{tree} expressions are built using functions such as, for
example, @code{fold_build2_loc}. For two tree variables @code{a} and
@code{b}, both of which have the type @code{gfc_arry_index_type},
calculation @code{c = a * b} would be done by
@smallexample
c = fold_build2_loc (input_location, MULT_EXPR,
gfc_array_index_type, a, b);
@end smallexample
The types have to agree, otherwise internal compiler errors will occur
at a later stage. Expressions can be converted to a different type
using @code{fold_convert}.
Accessing individual members in the @code{tree} structures should not
be done. Rather, access should be done via macros.
One basic data structure is the @code{stmtblock_t} struct. This is
used for holding a list of statements, expressed as @code{tree}
expressions. If a block is created using @code{gfc_start_block}, it
has its own scope for variables; if it is created using
@code{gfc_init_block}, it does not have its own scope.
It is possible to
@itemize @bullet
@item Add an expression to the end of a block using
@code{gfc_add_expr_to_block}
@item Add an expression to the beginning of a block using
@code{void gfc_prepend_expr_to_block}
@item Make a block into a single @code{tree} using
@code{gfc_finish_block}. For example, this is needed to put the
contents of a block into the @code{if} or @code{else} branch of
a @code{COND_EXPR}.
@end itemize
Variables are also @code{tree} expressions, they can be created using
@code{gfc_create_var}. Assigning to a variable can be done with
@code{gfc_add_modify}.
An example: Creating a default integer type variable in the current
scope with the prefix ``everything'' in the @code{stmt_block}
@code{block} and assigning the value 42 would be
@smallexample
tree var, *block;
/* Initialize block somewhere here. */
var = gfc_create_var (integer_type_node, "everything");
gfc_add_modify (block, var, build_int_cst (integer_type_node, 42));
@end smallexample
@node Converting Expressions
@section Converting Expressions to tree
Converting expressions to @code{tree} is done by functions called
@code{gfc_conv_*}.
The central data structure for a GENERIC expression is the
@code{gfc_se} structure. Its @code{expr} member is a @code{tree} that
holds the value of the expression. A @code{gfc_se} structure is
initialized using @code{gfc_init_se}; it needs to be embedded in an
outer @code{gfc_se}.
Evaluating Fortran expressions often require things to be done before
and after evaluation of the expression, for example code for the
allocation of a temporary variable and its subsequent deallocation.
Therefore, @code{gfc_se} contains the members @code{pre} and
@code{post}, which point to @code{stmt_block} blocks for code that
needs to be executed before and after evaluation of the expression.
When using a local @code{gfc_se} to convert some expression, it is
often necessary to add the generated @code{pre} and @code{post} blocks
to the @code{pre} or @code{post} blocks of the outer @code{gfc_se}.
Code like this (lifted from @file{trans-expr.cc}) is fairly common:
@smallexample
gfc_se cont_se;
tree cont_var;
/* cont_var = is_contiguous (expr); . */
gfc_init_se (&cont_se, parmse);
gfc_conv_is_contiguous_expr (&cont_se, expr);
gfc_add_block_to_block (&se->pre, &(&cont_se)->pre);
gfc_add_modify (&se->pre, cont_var, cont_se.expr);
gfc_add_block_to_block (&se->pre, &(&cont_se)->post);
@end smallexample
Conversion functions which need a @code{gfc_se} structure will have a
corresponding argument.
@code{gfc_se} also contains pointers to a @code{gfc_ss} and a
@code{gfc_loopinfo} structure. These are needed by the scalarizer.
@node Translating Statements
@section Translating statements
Translating statements to @code{tree} is done by functions called
@code{gfc_trans_*}. These functions usually get passed a
@code{gfc_code} structure, evaluate any expressions and then
return a @code{tree} structure.
@node Accessing Declarations
@section Accessing declarations
@code{gfc_symbol}, @code{gfc_charlen} and other front-end structures
contain a @code{backend_decl} variable, which contains the @code{tree}
used for accessing that entity in the middle-end.
Accessing declarations is usually done by functions called
@code{gfc_get*}.
@c ---------------------------------------------------------------------
@c LibGFortran
@c ---------------------------------------------------------------------
@node LibGFortran
@chapter The LibGFortran Runtime Library
@menu
* Symbol Versioning:: Symbol Versioning.
@end menu
@c ---------------------------------------------------------------------
@c Symbol Versioning
@c ---------------------------------------------------------------------
@node Symbol Versioning
@section Symbol Versioning
@comment Based on https://gcc.gnu.org/wiki/SymbolVersioning,
@comment as of 2006-11-05, written by Janne Blomqvist.
In general, this capability exists only on a few platforms, thus there
is a need for configure magic so that it is used only on those targets
where it is supported.
The central concept in symbol versioning is the so-called map file,
which specifies the version node(s) exported symbols are labeled with.
Also, the map file is used to hide local symbols.
Some relevant references:
@itemize @bullet
@item
@uref{https://sourceware.org/binutils/docs/ld/VERSION.html,
GNU @command{ld} manual}
@item
@uref{https://www.akkadia.org/drepper/symbol-versioning, ELF Symbol
Versioning - Ulrich Depper}
@item
@uref{https://www.akkadia.org/drepper/dsohowto.pdf, How to Write Shared
Libraries - Ulrich Drepper (see Chapter 3)}
@end itemize
If one adds a new symbol to a library that should be exported, the new
symbol should be mentioned in the map file and a new version node
defined, e.g., if one adds a new symbols @code{foo} and @code{bar} to
libgfortran for the next GCC release, the following should be added to
the map file:
@smallexample
GFORTRAN_1.1 @{
global:
foo;
bar;
@} GFORTRAN_1.0;
@end smallexample
@noindent
where @code{GFORTRAN_1.0} is the version node of the current release,
and @code{GFORTRAN_1.1} is the version node of the next release where
foo and bar are made available.
If one wants to change an existing interface, it is possible by using
some asm trickery (from the @command{ld} manual referenced above):
@smallexample
__asm__(".symver original_foo,foo@@");
__asm__(".symver old_foo,foo@@VERS_1.1");
__asm__(".symver old_foo1,foo@@VERS_1.2");
__asm__(".symver new_foo,foo@@VERS_2.0");
@end smallexample
In this example, @code{foo@@} represents the symbol @code{foo} bound to
the unspecified base version of the symbol. The source file that
contains this example would define 4 C functions: @code{original_foo},
@code{old_foo}, @code{old_foo1}, and @code{new_foo}.
In this case the map file must contain @code{foo} in @code{VERS_1.1}
and @code{VERS_1.2} as well as in @code{VERS_2.0}.
@c ---------------------------------------------------------------------
@c GNU Free Documentation License
@c ---------------------------------------------------------------------
@include fdl.texi
@c ---------------------------------------------------------------------
@c Index
@c ---------------------------------------------------------------------
@node Index
@unnumbered Index
@printindex cp
@bye

5573
gcc/fortran/gfortran.texi Normal file
View File

File diff suppressed because it is too large Load Diff

15435
gcc/fortran/intrinsic.texi Normal file
View File

File diff suppressed because it is too large Load Diff

2133
gcc/fortran/invoke.texi Normal file
View File

File diff suppressed because it is too large Load Diff

521
gcc/go/gccgo.texi Normal file
View File

@ -0,0 +1,521 @@
\input texinfo @c -*-texinfo-*-
@setfilename gccgo.info
@settitle The GNU Go Compiler
@c Merge the standard indexes into a single one.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@include gcc-common.texi
@c Copyright years for this manual.
@set copyrights-go 2010-2022
@copying
@c man begin COPYRIGHT
Copyright @copyright{} @value{copyrights-go} 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 no
Invariant Sections, 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
@c man end
section entitled ``GNU Free Documentation License''.
@ignore
@c man begin COPYRIGHT
man page gfdl(7).
@c man end
@end ignore
@c man begin COPYRIGHT
(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.
@c man end
@end copying
@ifinfo
@format
@dircategory Software development
@direntry
* Gccgo: (gccgo). A GCC-based compiler for the Go language
@end direntry
@end format
@insertcopying
@end ifinfo
@titlepage
@title The GNU Go Compiler
@versionsubtitle
@author Ian Lance Taylor
@page
@vskip 0pt plus 1filll
Published by the Free Software Foundation @*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301, USA@*
@sp 1
@insertcopying
@end titlepage
@contents
@page
@node Top
@top Introduction
This manual describes how to use @command{gccgo}, the GNU compiler for
the Go programming language. This manual is specifically about
@command{gccgo}. For more information about the Go programming
language in general, including language specifications and standard
package documentation, see @uref{https://golang.org/}.
@menu
* Copying:: The GNU General Public License.
* GNU Free Documentation License::
How you can share and copy this manual.
* Invoking gccgo:: How to run gccgo.
* Import and Export:: Importing and exporting package data.
* Compiler Directives:: Comments to control compilation.
* C Interoperability:: Calling C from Go and vice-versa.
* Index:: Index.
@end menu
@include gpl_v3.texi
@include fdl.texi
@node Invoking gccgo
@chapter Invoking gccgo
@c man title gccgo A GCC-based compiler for the Go language
@ignore
@c man begin SYNOPSIS gccgo
gccgo [@option{-c}|@option{-S}]
[@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
[@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
[@option{-o} @var{outfile}] @var{infile}@dots{}
Only the most useful options are listed here; see below for the
remainder.
@c man end
@c man begin SEEALSO
gpl(7), gfdl(7), fsf-funding(7), gcc(1)
and the Info entries for @file{gccgo} and @file{gcc}.
@c man end
@end ignore
@c man begin DESCRIPTION gccgo
The @command{gccgo} command is a frontend to @command{gcc} and
supports many of the same options. @xref{Option Summary, , Option
Summary, gcc, Using the GNU Compiler Collection (GCC)}. This manual
only documents the options specific to @command{gccgo}.
The @command{gccgo} command may be used to compile Go source code into
an object file, link a collection of object files together, or do both
in sequence.
Go source code is compiled as packages. A package consists of one or
more Go source files. All the files in a single package must be
compiled together, by passing all the files as arguments to
@command{gccgo}. A single invocation of @command{gccgo} may only
compile a single package.
One Go package may @code{import} a different Go package. The imported
package must have already been compiled; @command{gccgo} will read
the import data directly from the compiled package. When this package
is later linked, the compiled form of the package must be included in
the link command.
Go programs must generally be compiled with debugging information, and
@option{-g1} is the default as described below. Stripping a Go
program will generally cause it to misbehave or fail.
@c man end
@c man begin OPTIONS gccgo
@table @gcctabopt
@item -I@var{dir}
@cindex @option{-I}
Specify a directory to use when searching for an import package at
compile time.
@item -L@var{dir}
@cindex @option{-L}
When linking, specify a library search directory, as with
@command{gcc}.
@item -fgo-pkgpath=@var{string}
@cindex @option{-fgo-pkgpath}
Set the package path to use. This sets the value returned by the
PkgPath method of reflect.Type objects. It is also used for the names
of globally visible symbols. The argument to this option should
normally be the string that will be used to import this package after
it has been installed; in other words, a pathname within the
directories specified by the @option{-I} option.
@item -fgo-prefix=@var{string}
@cindex @option{-fgo-prefix}
An alternative to @option{-fgo-pkgpath}. The argument will be
combined with the package name from the source file to produce the
package path. If @option{-fgo-pkgpath} is used, @option{-fgo-prefix}
will be ignored.
Go permits a single program to include more than one package with the
same name in the @code{package} clause in the source file, though
obviously the two packages must be imported using different pathnames.
In order for this to work with @command{gccgo}, either
@option{-fgo-pkgpath} or @option{-fgo-prefix} must be specified when
compiling a package.
Using either @option{-fgo-pkgpath} or @option{-fgo-prefix} disables
the special treatment of the @code{main} package and permits that
package to be imported like any other.
@item -fgo-relative-import-path=@var{dir}
@cindex @option{-fgo-relative-import-path}
A relative import is an import that starts with @file{./} or
@file{../}. If this option is used, @command{gccgo} will use
@var{dir} as a prefix for the relative import when searching for it.
@item -frequire-return-statement
@itemx -fno-require-return-statement
@cindex @option{-frequire-return-statement}
@cindex @option{-fno-require-return-statement}
By default @command{gccgo} will warn about functions which have one or
more return parameters but lack an explicit @code{return} statement.
This warning may be disabled using
@option{-fno-require-return-statement}.
@item -fgo-check-divide-zero
@cindex @option{-fgo-check-divide-zero}
@cindex @option{-fno-go-check-divide-zero}
Add explicit checks for division by zero. In Go a division (or
modulos) by zero causes a panic. On Unix systems this is detected in
the runtime by catching the @code{SIGFPE} signal. Some processors,
such as PowerPC, do not generate a SIGFPE on division by zero. Some
runtimes do not generate a signal that can be caught. On those
systems, this option may be used. Or the checks may be removed via
@option{-fno-go-check-divide-zero}. This option is currently on by
default, but in the future may be off by default on systems that do
not require it.
@item -fgo-check-divide-overflow
@cindex @option{-fgo-check-divide-overflow}
@cindex @option{-fno-go-check-divide-overflow}
Add explicit checks for division overflow. For example, division
overflow occurs when computing @code{INT_MIN / -1}. In Go this should
be wrapped, to produce @code{INT_MIN}. Some processors, such as x86,
generate a trap on division overflow. On those systems, this option
may be used. Or the checks may be removed via
@option{-fno-go-check-divide-overflow}. This option is currently on
by default, but in the future may be off by default on systems that do
not require it.
@item -fno-go-optimize-allocs
@cindex @option{-fno-go-optimize-allocs}
Disable escape analysis, which tries to allocate objects on the stack
rather than the heap.
@item -fgo-debug-escape@var{n}
@cindex @option{-fgo-debug-escape}
Output escape analysis debugging information. Larger values of
@var{n} generate more information.
@item -fgo-debug-escape-hash=@var{n}
@cindex @option{-fgo-debug-escape-hash}
A hash value to debug escape analysis. @var{n} is a binary string.
This runs escape analysis only on functions whose names hash to values
that match the given suffix @var{n}. This can be used to binary
search across functions to uncover escape analysis bugs.
@item -fgo-debug-optimization
@cindex @option{-fgo-debug-optimization}
@cindex @option{-fno-go-debug-optimization}
Output optimization diagnostics.
@item -fgo-c-header=@var{file}
@cindex @option{-fgo-c-header}
Write top-level named Go struct definitions to @var{file} as C code.
This is used when compiling the runtime package.
@item -fgo-compiling-runtime
@cindex @option{-fgo-compiling-runtime}
Apply special rules for compiling the runtime package. Implicit
memory allocation is forbidden. Some additional compiler directives
are supported.
@item -fgo-embedcfg=@var{file}
@cindex @option{-fgo-embedcfg}
Identify a JSON file used to map patterns used with special
@code{//go:embed} comments to the files named by the patterns. The
JSON file should have two components: @code{Patterns} maps each
pattern to a list of file names, and @code{Files} maps each file name
to a full path to the file. This option is intended for use by the
@command{go} command to implement @code{//go:embed}.
@item -g
@cindex @option{-g for gccgo}
This is the standard @command{gcc} option (@pxref{Debugging Options, ,
Debugging Options, gcc, Using the GNU Compiler Collection (GCC)}). It
is mentioned here because by default @command{gccgo} turns on
debugging information generation with the equivalent of the standard
option @option{-g1}. This is because Go programs require debugging
information to be available in order to get backtrace information. An
explicit @option{-g0} may be used to disable the generation of
debugging information, in which case certain standard library
functions, such as @code{runtime.Callers}, will not operate correctly.
@end table
@c man end
@node Import and Export
@chapter Import and Export
When @command{gccgo} compiles a package which exports anything, the
export information will be stored directly in the object file. When a
package is imported, @command{gccgo} must be able to find the file.
@cindex @file{.gox}
When Go code imports the package @file{@var{gopackage}}, @command{gccgo}
will look for the import data using the following filenames, using the
first one that it finds.
@table @file
@item @var{gopackage}.gox
@item lib@var{gopackage}.so
@item lib@var{gopackage}.a
@item @var{gopackage}.o
@end table
The compiler will search for these files in the directories named by
any @option{-I} options, in order in which the directories appear on
the command line. The compiler will then search several standard
system directories. Finally the compiler will search the current
directory (to search the current directory earlier, use @samp{-I.}).
The compiler will extract the export information directly from the
compiled object file. The file @file{@var{gopackage}.gox} will
typically contain nothing but export data. This can be generated from
@file{@var{gopackage}.o} via
@smallexample
objcopy -j .go_export @var{gopackage}.o @var{gopackage}.gox
@end smallexample
For example, it may be desirable to extract the export information
from several different packages into their independent
@file{@var{gopackage}.gox} files, and then to combine the different
package object files together into a single shared library or archive.
At link time you must explicitly tell @command{gccgo} which files to
link together into the executable, as is usual with @command{gcc}.
This is different from the behavior of other Go compilers.
@node Compiler Directives
@chapter Compiler Directives
The Go compiler supports a few compiler directives. A compiler
directive uses a @code{//} comment at the start of a line. There must
be no space between the @code{//} and the name of the directive.
@table @code
@item //line @var{file}:@var{line}
The @code{//line} directive specifies that the source line that
follows should be recorded as having come from the given file path and
line number. Successive lines are recorded using increasing line
numbers, until the next directive. This directive typically appears
in machine-generated code, so that compilers and debuggers will show
lines in the original input to the generator.
@item //extern @var{extern_name}
The @code{extern} directive sets the externally visible name of the
next function declaration. See @ref{Function Names}.
@item //go:compile @var{go_name} @var{extern_name}
The @code{go:compile} directives sets the externally visible name of a
function definition or declaration. See @ref{Function Names}.
@item //go:noescape
The @code{//go:noescape} directive specifies that the next declaration
in the file, which must be a func without a body (meaning that it has
an implementation not written in Go) does not allow any of the
pointers passed as arguments to escape into the heap or into the
values returned from the function. This information can be used during
the compiler's escape analysis of Go code calling the function.
@item //go:nosplit
The @code{//go:nosplit} directive specifies that the next function
declared in the file must not include a stack overflow check. This is
most commonly used by low-level runtime sources invoked at times when
it is unsafe for the calling goroutine to be preempted.
@item //go:noinline
The @code{//go:noinline} directive specifies that the next function
defined in the file may not be inlined.
@end table
@node C Interoperability
@chapter C Interoperability
When using @command{gccgo} there is limited interoperability with C,
or with C++ code compiled using @code{extern "C"}.
This information is provided largely for documentation purposes. For
ordinary use it is best to build programs with the go tool and then
use @code{import "C"}, as described at
@url{https://golang.org/cmd/cgo}.
@menu
* C Type Interoperability:: How C and Go types match up.
* Function Names:: How Go functions are named.
@end menu
@node C Type Interoperability
@section C Type Interoperability
Basic types map directly: an @code{int} in Go is an @code{int} in C,
etc. Go @code{byte} is equivalent to C @code{unsigned char}.
Pointers in Go are pointers in C. A Go @code{struct} is the same as C
@code{struct} with the same field names and types.
@cindex @code{string} in C
The Go @code{string} type is currently defined as a two-element
structure:
@smallexample
struct __go_string @{
const unsigned char *__data;
int __length;
@};
@end smallexample
You can't pass arrays between C and Go. However, a pointer to an
array in Go is equivalent to a C pointer to the equivalent of the
element type. For example, Go @code{*[10]int} is equivalent to C
@code{int*}, assuming that the C pointer does point to 10 elements.
@cindex @code{slice} in C
A slice in Go is a structure. The current definition is:
@smallexample
struct __go_slice @{
void *__values;
int __count;
int __capacity;
@};
@end smallexample
The type of a Go function with no receiver is equivalent to a C
function whose parameter types are equivalent. When a Go function
returns more than one value, the C function returns a struct. For
example, these functions have equivalent types:
@smallexample
func GoFunction(int) (int, float)
struct @{ int i; float f; @} CFunction(int)
@end smallexample
A pointer to a Go function is equivalent to a pointer to a C function
when the functions have equivalent types.
Go @code{interface}, @code{channel}, and @code{map} types have no
corresponding C type (@code{interface} is a two-element struct and
@code{channel} and @code{map} are pointers to structs in C, but the
structs are deliberately undocumented). C @code{enum} types
correspond to some integer type, but precisely which one is difficult
to predict in general; use a cast. C @code{union} types have no
corresponding Go type. C @code{struct} types containing bitfields
have no corresponding Go type. C++ @code{class} types have no
corresponding Go type.
Memory allocation is completely different between C and Go, as Go uses
garbage collection. The exact guidelines in this area are
undetermined, but it is likely that it will be permitted to pass a
pointer to allocated memory from C to Go. The responsibility of
eventually freeing the pointer will remain with C side, and of course
if the C side frees the pointer while the Go side still has a copy the
program will fail. When passing a pointer from Go to C, the Go
function must retain a visible copy of it in some Go variable.
Otherwise the Go garbage collector may delete the pointer while the C
function is still using it.
@node Function Names
@section Function Names
@cindex @code{extern}
@cindex external names
Go code can call C functions directly using the @code{//extern} or
@code{//go:linkname} compiler directives. An @code{//extern}
directive must be at the beginning of the line and must start with
@code{//extern}. This must be followed by a space and then the
external name of the function. The function declaration must be on
the line immediately after the comment. For example, here is how the
C function @code{open} can be declared in Go:
@smallexample
//extern open
func c_open(name *byte, mode int, perm int) int
@end smallexample
You can do the same thing using the @code{//go:linkname} compiler
directive. The @code{//go:linkname} directive must be at the start of
the line. It is followed by whitespace, the name of the Go function,
more whitespace, and the external name of the function. Unlike
@code{//extern}, @code{//go:linkname} does not need to appear
immediately adjacent to the function definition or declaration.
@smallexample
//go:linkname c_open open
func c_open(name *byte, mode int, perm int) int
@end smallexample
The C function naturally expects a nul terminated string, which in Go
is equivalent to a pointer to an array (not a slice!) of @code{byte}
with a terminating zero byte. So a sample call from Go would look
like (after importing the @code{os} package):
@smallexample
var name = [4]byte@{'f', 'o', 'o', 0@};
i := c_open(&name[0], os.O_RDONLY, 0);
@end smallexample
Note that this serves as an example only. To open a file in Go please
use Go's @code{os.Open} function instead.
The name of Go functions accessed from C is subject to change. At
present the name of a Go function that does not have a receiver is
@code{pkgpath.Functionname}. The @var{pkgpath} is set by the
@option{-fgo-pkgpath} option used when the package is compiled; if the
option is not used, the default is @code{go.@var{packagename}}. To
call the function from C you must set the name using the @command{gcc}
@code{__asm__} extension.
@smallexample
extern int go_function(int) __asm__ ("mypkgpath.Function");
@end smallexample
@node Index
@unnumbered Index
@printindex cp
@bye

4884
libgomp/libgomp.texi Normal file
View File

File diff suppressed because it is too large Load Diff

15
libiberty/at-file.texi Normal file
View File

@ -0,0 +1,15 @@
@c This file is designed to be included in manuals that use
@c expandargv.
@item @@@var{file}
Read command-line options from @var{file}. The options read are
inserted in place of the original @@@var{file} option. If @var{file}
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
Options in @var{file} are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The @var{file} may itself contain additional
@@@var{file} options; any such options will be processed recursively.

560
libiberty/copying-lib.texi Normal file
View File

@ -0,0 +1,560 @@
@node Library Copying
@appendixsec GNU LESSER GENERAL PUBLIC LICENSE
@cindex LGPL, Lesser General Public License
@center Version 2.1, February 1999
@display
Copyright @copyright{} 1991-2022 Free Software Foundation, Inc.
51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[This is the first released version of the Lesser GPL. It also counts
as the successor of the GNU Library Public License, version 2, hence the
version number 2.1.]
@end display
@appendixsubsec Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software---to make sure the software is free for all its users.
This license, the Lesser General Public License, applies to some
specially designated software---typically libraries---of the Free
Software Foundation and other authors who decide to use it. You can use
it too, but we suggest you first think carefully about whether this
license or the ordinary General Public License is the better strategy to
use in any particular case, based on the explanations below.
When we speak of free software, we are referring to freedom of use,
not price. Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of it
in new free programs; and that you are informed that you can do these
things.
To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights. These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.
For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you. You must make sure that they, too, receive or can get the source
code. If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it. And you must show them these terms so they know their rights.
We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.
To protect each distributor, we want to make it very clear that
there is no warranty for the free library. Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.
Finally, software patents pose a constant threat to the existence of
any free program. We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder. Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.
Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License. This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License. We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.
When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library. The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom. The Lesser General
Public License permits more lax criteria for linking other code with
the library.
We call this license the @dfn{Lesser} General Public License because it
does @emph{Less} to protect the user's freedom than the ordinary General
Public License. It also provides other free software developers Less
of an advantage over competing non-free programs. These disadvantages
are the reason we use the ordinary General Public License for many
libraries. However, the Lesser license provides advantages in certain
special circumstances.
For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard. To achieve this, non-free programs must be
allowed to use the library. A more frequent case is that a free
library does the same job as widely used non-free libraries. In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.
In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software. For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.
Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.
The precise terms and conditions for copying, distribution and
modification follow. Pay close attention to the difference between a
``work based on the library'' and a ``work that uses the library''. The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.
@iftex
@appendixsubsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifinfo
@center GNU LESSER GENERAL PUBLIC LICENSE
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifinfo
@enumerate 0
@item
This License Agreement applies to any software library or other program
which contains a notice placed by the copyright holder or other
authorized party saying it may be distributed under the terms of this
Lesser General Public License (also called ``this License''). Each
licensee is addressed as ``you''.
A ``library'' means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
The ``Library'', below, refers to any such software library or work
which has been distributed under these terms. A ``work based on the
Library'' means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation is
included without limitation in the term ``modification''.)
``Source code'' for a work means the preferred form of the work for
making modifications to it. For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does
and what the program that uses the Library does.
@item
You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.
You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
@item
You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
@enumerate a
@item
The modified work must itself be a software library.
@item
You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
@item
You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
@item
If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.
(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application. Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
@end enumerate
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.
In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
@item
You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library. To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License. (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.) Do not make any other change in
these notices.
Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
@item
You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
@item
A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a ``work that uses the Library''. Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
However, linking a ``work that uses the Library'' with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a ``work that uses the
library''. The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
When a ``work that uses the Library'' uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library. The
threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work. (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
@item
As an exception to the Sections above, you may also combine or
link a ``work that uses the Library'' with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do one
of these things:
@enumerate a
@item
Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable ``work that
uses the Library'', as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library. (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)
@item
Use a suitable shared library mechanism for linking with the Library. A
suitable mechanism is one that (1) uses at run time a copy of the
library already present on the user's computer system, rather than
copying library functions into the executable, and (2) will operate
properly with a modified version of the library, if the user installs
one, as long as the modified version is interface-compatible with the
version that the work was made with.
@item
Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.
@item
If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.
@item
Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
@end enumerate
For an executable, the required form of the ``work that uses the
Library'' must include any data and utility programs needed for
reproducing the executable from it. However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies the
executable.
It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
@item
You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
@enumerate a
@item
Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities. This must be distributed under the terms of the
Sections above.
@item
Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
@end enumerate
@item
You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License. However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
@item
You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Library or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
@item
Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.
@item
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
@item
If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded. In such case, this License incorporates the limitation as if
written in the body of this License.
@item
The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library
specifies a version number of this License which applies to it and
``any later version'', you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
@item
If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission. For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this. Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
@center NO WARRANTY
@item
BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
@end enumerate
@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo
@page
@appendixsubsec How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change. You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).
To apply these terms, attach the following notices to the library. It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
``copyright'' line and a pointer to where the full notice is found.
@smallexample
@var{one line to give the library's name and an idea of what it does.}
Copyright (C) @var{year} @var{name of author}
This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or (at
your option) any later version.
This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
USA.
@end smallexample
Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the library, if
necessary. Here is a sample; alter the names:
@smallexample
Yoyodyne, Inc., hereby disclaims all copyright interest in the library
`Frob' (a library for tweaking knobs) written by James Random Hacker.
@var{signature of Ty Coon}, 1 April 1990
Ty Coon, President of Vice
@end smallexample
That's all there is to it!

2063
libiberty/functions.texi Normal file
View File

File diff suppressed because it is too large Load Diff

313
libiberty/libiberty.texi Normal file
View File

@ -0,0 +1,313 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename libiberty.info
@settitle @sc{gnu} libiberty
@c %**end of header
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex pg cp
@finalout
@c %**end of header
@dircategory GNU libraries
@direntry
* Libiberty: (libiberty). Library of utility functions which
are missing or broken on some systems.
@end direntry
@macro libib
@code{libiberty}
@end macro
@ifinfo
This manual describes the GNU @libib library of utility subroutines.
Copyright @copyright{} 2001-2022 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 no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore
@end ifinfo
@titlepage
@title @sc{gnu} libiberty
@author Phil Edwards et al.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2001-2022 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 no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
@end titlepage
@contents
@page
@ifnottex
@node Top,Using,,
@top Introduction
The @libib{} library is a collection of subroutines used by various
GNU programs. It is available under the Library General Public
License; for more information, see @ref{Library Copying}.
@end ifnottex
@menu
* Using:: How to use libiberty in your code.
* Overview:: Overview of available function groups.
* Functions:: Available functions, macros, and global variables.
* Licenses:: The various licenses under which libiberty sources are
distributed.
* Index:: Index of functions and categories.
@end menu
@node Using
@chapter Using
@cindex using libiberty
@cindex libiberty usage
@cindex how to use
@c THIS SECTION IS CRAP AND NEEDS REWRITING BADLY.
To date, @libib{} is generally not installed on its own. It has evolved
over years but does not have its own version number nor release schedule.
Possibly the easiest way to use @libib{} in your projects is to drop the
@libib{} code into your project's sources, and to build the library along
with your own sources; the library would then be linked in at the end. This
prevents any possible version mismatches with other copies of libiberty
elsewhere on the system.
Passing @option{--enable-install-libiberty} to the @command{configure}
script when building @libib{} causes the header files and archive library
to be installed when @kbd{make install} is run. This option also takes
an (optional) argument to specify the installation location, in the same
manner as @option{--prefix}.
For your own projects, an approach which offers stability and flexibility
is to include @libib{} with your code, but allow the end user to optionally
choose to use a previously-installed version instead. In this way the
user may choose (for example) to install @libib{} as part of GCC, and use
that version for all software built with that compiler. (This approach
has proven useful with software using the GNU @code{readline} library.)
Making use of @libib{} code usually requires that you include one or more
header files from the @libib{} distribution. (They will be named as
necessary in the function descriptions.) At link time, you will need to
add @option{-liberty} to your link command invocation.
@node Overview
@chapter Overview
Functions contained in @libib{} can be divided into three general categories.
@menu
* Supplemental Functions:: Providing functions which don't exist
on older operating systems.
* Replacement Functions:: These functions are sometimes buggy or
unpredictable on some operating systems.
* Extensions:: Functions which provide useful extensions
or safety wrappers around existing code.
@end menu
@node Supplemental Functions
@section Supplemental Functions
@cindex supplemental functions
@cindex functions, supplemental
@cindex functions, missing
Certain operating systems do not provide functions which have since
become standardized, or at least common. For example, the Single
Unix Specification Version 2 requires that the @code{basename}
function be provided, but an OS which predates that specification
might not have this function. This should not prevent well-written
code from running on such a system.
Similarly, some functions exist only among a particular ``flavor''
or ``family'' of operating systems. As an example, the @code{bzero}
function is often not present on systems outside the BSD-derived
family of systems.
Many such functions are provided in @libib{}. They are quickly
listed here with little description, as systems which lack them
become less and less common. Each function @var{foo} is implemented
in @file{@var{foo}.c} but not declared in any @libib{} header file; more
comments and caveats for each function's implementation are often
available in the source file. Generally, the function can simply
be declared as @code{extern}.
@node Replacement Functions
@section Replacement Functions
@cindex replacement functions
@cindex functions, replacement
Some functions have extremely limited implementations on different
platforms. Other functions are tedious to use correctly; for example,
proper use of @code{malloc} calls for the return value to be checked and
appropriate action taken if memory has been exhausted. A group of
``replacement functions'' is available in @libib{} to address these issues
for some of the most commonly used subroutines.
All of these functions are declared in the @file{libiberty.h} header
file. Many of the implementations will use preprocessor macros set by
GNU Autoconf, if you decide to make use of that program. Some of these
functions may call one another.
@menu
* Memory Allocation:: Testing and handling failed memory
requests automatically.
* Exit Handlers:: Calling routines on program exit.
* Error Reporting:: Mapping errno and signal numbers to
more useful string formats.
@end menu
@node Memory Allocation
@subsection Memory Allocation
@cindex memory allocation
The functions beginning with the letter @samp{x} are wrappers around
standard functions; the functions provided by the system environment
are called and their results checked before the results are passed back
to client code. If the standard functions fail, these wrappers will
terminate the program. Thus, these versions can be used with impunity.
@node Exit Handlers
@subsection Exit Handlers
@cindex exit handlers
The existence and implementation of the @code{atexit} routine varies
amongst the flavors of Unix. @libib{} provides an unvarying dependable
implementation via @code{xatexit} and @code{xexit}.
@node Error Reporting
@subsection Error Reporting
@cindex error reporting
These are a set of routines to facilitate programming with the system
@code{errno} interface. The @libib{} source file @file{strerror.c}
contains a good deal of documentation for these functions.
@c signal stuff
@node Extensions
@section Extensions
@cindex extensions
@cindex functions, extension
@libib{} includes additional functionality above and beyond standard
functions, which has proven generically useful in GNU programs, such as
obstacks and regex. These functions are often copied from other
projects as they gain popularity, and are included here to provide a
central location from which to use, maintain, and distribute them.
@menu
* Obstacks:: Stacks of arbitrary objects.
@end menu
@c This is generated from the glibc manual using contrib/make-obstacks-texi.pl
@include obstacks.texi
@node Functions
@chapter Function, Variable, and Macro Listing.
@include functions.texi
@node Licenses
@appendix Licenses
@menu
* Library Copying:: The GNU Library General Public License
* BSD:: Regents of the University of California
@end menu
@c This takes care of Library Copying. It is the copying-lib.texi from the
@c GNU web site, with its @node line altered to make makeinfo shut up.
@include copying-lib.texi
@page
@node BSD
@appendixsec BSD
Copyright @copyright{} 1990 Regents of the University of California.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
@enumerate
@item
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
@item
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
@item
[rescinded 22 July 1999]
@item
Neither the name of the University nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
@end enumerate
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
@node Index
@unnumbered Index
@printindex cp
@bye

774
libiberty/obstacks.texi Normal file
View File

@ -0,0 +1,774 @@
@node Obstacks
@subsection Obstacks
@cindex obstacks
An @dfn{obstack} is a pool of memory containing a stack of objects. You
can create any number of separate obstacks, and then allocate objects in
specified obstacks. Within each obstack, the last object allocated must
always be the first one freed, but distinct obstacks are independent of
each other.
Aside from this one constraint of order of freeing, obstacks are totally
general: an obstack can contain any number of objects of any size. They
are implemented with macros, so allocation is usually very fast as long as
the objects are usually small. And the only space overhead per object is
the padding needed to start each object on a suitable boundary.
@menu
* Creating Obstacks:: How to declare an obstack in your program.
* Preparing for Obstacks:: Preparations needed before you can
use obstacks.
* Allocation in an Obstack:: Allocating objects in an obstack.
* Freeing Obstack Objects:: Freeing objects in an obstack.
* Obstack Functions:: The obstack functions are really macros.
* Growing Objects:: Making an object bigger by stages.
* Extra Fast Growing:: Extra-high-efficiency (though more
complicated) growing objects.
* Status of an Obstack:: Inquiries about the status of an obstack.
* Obstacks Data Alignment:: Controlling alignment of objects in obstacks.
* Obstack Chunks:: How obstacks obtain and release chunks;
efficiency considerations.
* Summary of Obstacks::
@end menu
@node Creating Obstacks
@subsubsection Creating Obstacks
The utilities for manipulating obstacks are declared in the header
file @file{obstack.h}.
@pindex obstack.h
@comment obstack.h
@comment GNU
@deftp {Data Type} {struct obstack}
An obstack is represented by a data structure of type @code{struct
obstack}. This structure has a small fixed size; it records the status
of the obstack and how to find the space in which objects are allocated.
It does not contain any of the objects themselves. You should not try
to access the contents of the structure directly; use only the macros
described in this chapter.
@end deftp
You can declare variables of type @code{struct obstack} and use them as
obstacks, or you can allocate obstacks dynamically like any other kind
of object. Dynamic allocation of obstacks allows your program to have a
variable number of different stacks. (You can even allocate an
obstack structure in another obstack, but this is rarely useful.)
All the macros that work with obstacks require you to specify which
obstack to use. You do this with a pointer of type @code{struct obstack
*}. In the following, we often say ``an obstack'' when strictly
speaking the object at hand is such a pointer.
The objects in the obstack are packed into large blocks called
@dfn{chunks}. The @code{struct obstack} structure points to a chain of
the chunks currently in use.
The obstack library obtains a new chunk whenever you allocate an object
that won't fit in the previous chunk. Since the obstack library manages
chunks automatically, you don't need to pay much attention to them, but
you do need to supply a function which the obstack library should use to
get a chunk. Usually you supply a function which uses @code{malloc}
directly or indirectly. You must also supply a function to free a chunk.
These matters are described in the following section.
@node Preparing for Obstacks
@subsubsection Preparing for Using Obstacks
Each source file in which you plan to use obstacks
must include the header file @file{obstack.h}, like this:
@smallexample
#include <obstack.h>
@end smallexample
@findex obstack_chunk_alloc
@findex obstack_chunk_free
Also, if the source file uses the macro @code{obstack_init}, it must
declare or define two macros that will be called by the
obstack library. One, @code{obstack_chunk_alloc}, is used to allocate
the chunks of memory into which objects are packed. The other,
@code{obstack_chunk_free}, is used to return chunks when the objects in
them are freed. These macros should appear before any use of obstacks
in the source file.
Usually these are defined to use @code{malloc} via the intermediary
@code{xmalloc} (@pxref{Unconstrained Allocation, , , libc, The GNU C Library Reference Manual}). This is done with
the following pair of macro definitions:
@smallexample
#define obstack_chunk_alloc xmalloc
#define obstack_chunk_free free
@end smallexample
@noindent
Though the memory you get using obstacks really comes from @code{malloc},
using obstacks is faster because @code{malloc} is called less often, for
larger blocks of memory. @xref{Obstack Chunks}, for full details.
At run time, before the program can use a @code{struct obstack} object
as an obstack, it must initialize the obstack by calling
@code{obstack_init} or one of its variants, @code{obstack_begin},
@code{obstack_specify_allocation}, or
@code{obstack_specify_allocation_with_arg}.
@comment obstack.h
@comment GNU
@deftypefun int obstack_init (struct obstack *@var{obstack-ptr})
Initialize obstack @var{obstack-ptr} for allocation of objects. This
macro calls the obstack's @code{obstack_chunk_alloc} function. If
allocation of memory fails, the function pointed to by
@code{obstack_alloc_failed_handler} is called. The @code{obstack_init}
macro always returns 1 (Compatibility notice: Former versions of
obstack returned 0 if allocation failed).
@end deftypefun
Here are two examples of how to allocate the space for an obstack and
initialize it. First, an obstack that is a static variable:
@smallexample
static struct obstack myobstack;
@dots{}
obstack_init (&myobstack);
@end smallexample
@noindent
Second, an obstack that is itself dynamically allocated:
@smallexample
struct obstack *myobstack_ptr
= (struct obstack *) xmalloc (sizeof (struct obstack));
obstack_init (myobstack_ptr);
@end smallexample
@comment obstack.h
@comment GNU
@deftypefun int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size)
Like @code{obstack_init}, but specify chunks to be at least
@var{chunk_size} bytes in size.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *))
Like @code{obstack_init}, specifying chunk size, chunk
alignment, and memory allocation functions. A @var{chunk_size} or
@var{alignment} of zero results in the default size or alignment
respectively being used.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg)
Like @code{obstack_specify_allocation}, but specifying memory
allocation functions that take an extra first argument, @var{arg}.
@end deftypefun
@comment obstack.h
@comment GNU
@defvar obstack_alloc_failed_handler
The value of this variable is a pointer to a function that
@code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate
memory. The default action is to print a message and abort.
You should supply a function that either calls @code{exit}
(@pxref{Program Termination, , , libc, The GNU C Library Reference Manual}) or @code{longjmp} (@pxref{Non-Local
Exits, , , libc, The GNU C Library Reference Manual}) and doesn't return.
@smallexample
void my_obstack_alloc_failed (void)
@dots{}
obstack_alloc_failed_handler = &my_obstack_alloc_failed;
@end smallexample
@end defvar
@node Allocation in an Obstack
@subsubsection Allocation in an Obstack
@cindex allocation (obstacks)
The most direct way to allocate an object in an obstack is with
@code{obstack_alloc}, which is invoked almost like @code{malloc}.
@comment obstack.h
@comment GNU
@deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size})
This allocates an uninitialized block of @var{size} bytes in an obstack
and returns its address. Here @var{obstack-ptr} specifies which obstack
to allocate the block in; it is the address of the @code{struct obstack}
object which represents the obstack. Each obstack macro
requires you to specify an @var{obstack-ptr} as the first argument.
This macro calls the obstack's @code{obstack_chunk_alloc} function if
it needs to allocate a new chunk of memory; it calls
@code{obstack_alloc_failed_handler} if allocation of memory by
@code{obstack_chunk_alloc} failed.
@end deftypefun
For example, here is a function that allocates a copy of a string @var{str}
in a specific obstack, which is in the variable @code{string_obstack}:
@smallexample
struct obstack string_obstack;
char *
copystring (char *string)
@{
size_t len = strlen (string) + 1;
char *s = (char *) obstack_alloc (&string_obstack, len);
memcpy (s, string, len);
return s;
@}
@end smallexample
To allocate a block with specified contents, use the macro @code{obstack_copy}.
@comment obstack.h
@comment GNU
@deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
This allocates a block and initializes it by copying @var{size}
bytes of data starting at @var{address}. It calls
@code{obstack_alloc_failed_handler} if allocation of memory by
@code{obstack_chunk_alloc} failed.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
Like @code{obstack_copy}, but appends an extra byte containing a null
character. This extra byte is not counted in the argument @var{size}.
@end deftypefun
The @code{obstack_copy0} macro is convenient for copying a sequence
of characters into an obstack as a null-terminated string. Here is an
example of its use:
@smallexample
char *
obstack_savestring (char *addr, size_t size)
@{
return obstack_copy0 (&myobstack, addr, size);
@}
@end smallexample
@noindent
Contrast this with the previous example of @code{savestring} using
@code{malloc} (@pxref{Basic Allocation, , , libc, The GNU C Library Reference Manual}).
@node Freeing Obstack Objects
@subsubsection Freeing Objects in an Obstack
@cindex freeing (obstacks)
To free an object allocated in an obstack, use the macro
@code{obstack_free}. Since the obstack is a stack of objects, freeing
one object automatically frees all other objects allocated more recently
in the same obstack.
@comment obstack.h
@comment GNU
@deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
If @var{object} is a null pointer, everything allocated in the obstack
is freed. Otherwise, @var{object} must be the address of an object
allocated in the obstack. Then @var{object} is freed, along with
everything allocated in @var{obstack} since @var{object}.
@end deftypefun
Note that if @var{object} is a null pointer, the result is an
uninitialized obstack. To free all memory in an obstack but leave it
valid for further allocation, call @code{obstack_free} with the address
of the first object allocated on the obstack:
@smallexample
obstack_free (obstack_ptr, first_object_allocated_ptr);
@end smallexample
Recall that the objects in an obstack are grouped into chunks. When all
the objects in a chunk become free, the obstack library automatically
frees the chunk (@pxref{Preparing for Obstacks}). Then other
obstacks, or non-obstack allocation, can reuse the space of the chunk.
@node Obstack Functions
@subsubsection Obstack Functions and Macros
@cindex macros
The interfaces for using obstacks are shown here as functions to
specify the return type and argument types, but they are really
defined as macros. This means that the arguments don't actually have
types, but they generally behave as if they have the types shown.
You can call these macros like functions, but you cannot use them in
any other way (for example, you cannot take their address).
Calling the macros requires a special precaution: namely, the first
operand (the obstack pointer) may not contain any side effects, because
it may be computed more than once. For example, if you write this:
@smallexample
obstack_alloc (get_obstack (), 4);
@end smallexample
@noindent
you will find that @code{get_obstack} may be called several times.
If you use @code{*obstack_list_ptr++} as the obstack pointer argument,
you will get very strange results since the incrementation may occur
several times.
If you use the GNU C compiler, this precaution is not necessary, because
various language extensions in GNU C permit defining the macros so as to
compute each argument only once.
Note that arguments other than the first will only be evaluated once,
even when not using GNU C.
@code{obstack.h} does declare a number of functions,
@code{_obstack_begin}, @code{_obstack_begin_1},
@code{_obstack_newchunk}, @code{_obstack_free}, and
@code{_obstack_memory_used}. You should not call these directly.
@node Growing Objects
@subsubsection Growing Objects
@cindex growing objects (in obstacks)
@cindex changing the size of a block (obstacks)
Because memory in obstack chunks is used sequentially, it is possible to
build up an object step by step, adding one or more bytes at a time to the
end of the object. With this technique, you do not need to know how much
data you will put in the object until you come to the end of it. We call
this the technique of @dfn{growing objects}. The special macros
for adding data to the growing object are described in this section.
You don't need to do anything special when you start to grow an object.
Using one of the macros to add data to the object automatically
starts it. However, it is necessary to say explicitly when the object is
finished. This is done with @code{obstack_finish}.
The actual address of the object thus built up is not known until the
object is finished. Until then, it always remains possible that you will
add so much data that the object must be copied into a new chunk.
While the obstack is in use for a growing object, you cannot use it for
ordinary allocation of another object. If you try to do so, the space
already added to the growing object will become part of the other object.
@comment obstack.h
@comment GNU
@deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size})
The most basic macro for adding to a growing object is
@code{obstack_blank}, which adds space without initializing it.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size})
To add a block of initialized space, use @code{obstack_grow}, which is
the growing-object analogue of @code{obstack_copy}. It adds @var{size}
bytes of data to the growing object, copying the contents from
@var{data}.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size})
This is the growing-object analogue of @code{obstack_copy0}. It adds
@var{size} bytes copied from @var{data}, followed by an additional null
character.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c})
To add one character at a time, use @code{obstack_1grow}.
It adds a single byte containing @var{c} to the growing object.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data})
Adding the value of a pointer one can use
@code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes
containing the value of @var{data}.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data})
A single value of type @code{int} can be added by using
@code{obstack_int_grow}. It adds @code{sizeof (int)} bytes to
the growing object and initializes them with the value of @var{data}.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr})
When you are finished growing the object, use
@code{obstack_finish} to close it off and return its final address.
Once you have finished the object, the obstack is available for ordinary
allocation or for growing another object.
@end deftypefun
When you build an object by growing it, you will probably need to know
afterward how long it became. You need not keep track of this as you grow
the object, because you can find out the length from the obstack
with @code{obstack_object_size}, before finishing the object.
@comment obstack.h
@comment GNU
@deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr})
This macro returns the current size of the growing object, in bytes.
Remember to call @code{obstack_object_size} @emph{before} finishing the object.
After it is finished, @code{obstack_object_size} will return zero.
@end deftypefun
If you have started growing an object and wish to cancel it, you should
finish it and then free it, like this:
@smallexample
obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
@end smallexample
@noindent
This has no effect if no object was growing.
@node Extra Fast Growing
@subsubsection Extra Fast Growing Objects
@cindex efficiency and obstacks
The usual macros for growing objects incur overhead for checking
whether there is room for the new growth in the current chunk. If you
are frequently constructing objects in small steps of growth, this
overhead can be significant.
You can reduce the overhead by using special ``fast growth''
macros that grow the object without checking. In order to have a
robust program, you must do the checking yourself. If you do this checking
in the simplest way each time you are about to add data to the object, you
have not saved anything, because that is what the ordinary growth
macros do. But if you can arrange to check less often, or check
more efficiently, then you make the program faster.
@code{obstack_room} returns the amount of room available
in the current chunk.
@comment obstack.h
@comment GNU
@deftypefun size_t obstack_room (struct obstack *@var{obstack-ptr})
This returns the number of bytes that can be added safely to the current
growing object (or to an object about to be started) in obstack
@var{obstack} using the fast growth macros.
@end deftypefun
While you know there is room, you can use these fast growth macros
for adding data to a growing object:
@comment obstack.h
@comment GNU
@deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c})
@code{obstack_1grow_fast} adds one byte containing the
character @var{c} to the growing object in obstack @var{obstack-ptr}.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data})
@code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
bytes containing the value of @var{data} to the growing object in
obstack @var{obstack-ptr}.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data})
@code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
containing the value of @var{data} to the growing object in obstack
@var{obstack-ptr}.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size})
@code{obstack_blank_fast} adds @var{size} bytes to the
growing object in obstack @var{obstack-ptr} without initializing them.
@end deftypefun
When you check for space using @code{obstack_room} and there is not
enough room for what you want to add, the fast growth macros
are not safe. In this case, simply use the corresponding ordinary
growth macro instead. Very soon this will copy the object to a
new chunk; then there will be lots of room available again.
So, each time you use an ordinary growth macro, check afterward for
sufficient space using @code{obstack_room}. Once the object is copied
to a new chunk, there will be plenty of space again, so the program will
start using the fast growth macros again.
Here is an example:
@smallexample
@group
void
add_string (struct obstack *obstack, const char *ptr, size_t len)
@{
while (len > 0)
@{
size_t room = obstack_room (obstack);
if (room == 0)
@{
/* @r{Not enough room. Add one character slowly,}
@r{which may copy to a new chunk and make room.} */
obstack_1grow (obstack, *ptr++);
len--;
@}
else
@{
if (room > len)
room = len;
/* @r{Add fast as much as we have room for.} */
len -= room;
while (room-- > 0)
obstack_1grow_fast (obstack, *ptr++);
@}
@}
@}
@end group
@end smallexample
@cindex shrinking objects
You can use @code{obstack_blank_fast} with a ``negative'' size
argument to make the current object smaller. Just don't try to shrink
it beyond zero length---there's no telling what will happen if you do
that. Earlier versions of obstacks allowed you to use
@code{obstack_blank} to shrink objects. This will no longer work.
@node Status of an Obstack
@subsubsection Status of an Obstack
@cindex obstack status
@cindex status of obstack
Here are macros that provide information on the current status of
allocation in an obstack. You can use them to learn about an object while
still growing it.
@comment obstack.h
@comment GNU
@deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr})
This macro returns the tentative address of the beginning of the
currently growing object in @var{obstack-ptr}. If you finish the object
immediately, it will have that address. If you make it larger first, it
may outgrow the current chunk---then its address will change!
If no object is growing, this value says where the next object you
allocate will start (once again assuming it fits in the current
chunk).
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr})
This macro returns the address of the first free byte in the current
chunk of obstack @var{obstack-ptr}. This is the end of the currently
growing object. If no object is growing, @code{obstack_next_free}
returns the same value as @code{obstack_base}.
@end deftypefun
@comment obstack.h
@comment GNU
@deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr})
This macro returns the size in bytes of the currently growing object.
This is equivalent to
@smallexample
((size_t) (obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})))
@end smallexample
@end deftypefun
@node Obstacks Data Alignment
@subsubsection Alignment of Data in Obstacks
@cindex alignment (in obstacks)
Each obstack has an @dfn{alignment boundary}; each object allocated in
the obstack automatically starts on an address that is a multiple of the
specified boundary. By default, this boundary is aligned so that
the object can hold any type of data.
To access an obstack's alignment boundary, use the macro
@code{obstack_alignment_mask}.
@comment obstack.h
@comment GNU
@deftypefn Macro size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr})
The value is a bit mask; a bit that is 1 indicates that the corresponding
bit in the address of an object should be 0. The mask value should be one
less than a power of 2; the effect is that all object addresses are
multiples of that power of 2. The default value of the mask is a value
that allows aligned objects to hold any type of data: for example, if
its value is 3, any type of data can be stored at locations whose
addresses are multiples of 4. A mask value of 0 means an object can start
on any multiple of 1 (that is, no alignment is required).
The expansion of the macro @code{obstack_alignment_mask} is an lvalue,
so you can alter the mask by assignment. For example, this statement:
@smallexample
obstack_alignment_mask (obstack_ptr) = 0;
@end smallexample
@noindent
has the effect of turning off alignment processing in the specified obstack.
@end deftypefn
Note that a change in alignment mask does not take effect until
@emph{after} the next time an object is allocated or finished in the
obstack. If you are not growing an object, you can make the new
alignment mask take effect immediately by calling @code{obstack_finish}.
This will finish a zero-length object and then do proper alignment for
the next object.
@node Obstack Chunks
@subsubsection Obstack Chunks
@cindex efficiency of chunks
@cindex chunks
Obstacks work by allocating space for themselves in large chunks, and
then parceling out space in the chunks to satisfy your requests. Chunks
are normally 4096 bytes long unless you specify a different chunk size.
The chunk size includes 8 bytes of overhead that are not actually used
for storing objects. Regardless of the specified size, longer chunks
will be allocated when necessary for long objects.
The obstack library allocates chunks by calling the function
@code{obstack_chunk_alloc}, which you must define. When a chunk is no
longer needed because you have freed all the objects in it, the obstack
library frees the chunk by calling @code{obstack_chunk_free}, which you
must also define.
These two must be defined (as macros) or declared (as functions) in each
source file that uses @code{obstack_init} (@pxref{Creating Obstacks}).
Most often they are defined as macros like this:
@smallexample
#define obstack_chunk_alloc malloc
#define obstack_chunk_free free
@end smallexample
Note that these are simple macros (no arguments). Macro definitions with
arguments will not work! It is necessary that @code{obstack_chunk_alloc}
or @code{obstack_chunk_free}, alone, expand into a function name if it is
not itself a function name.
If you allocate chunks with @code{malloc}, the chunk size should be a
power of 2. The default chunk size, 4096, was chosen because it is long
enough to satisfy many typical requests on the obstack yet short enough
not to waste too much memory in the portion of the last chunk not yet used.
@comment obstack.h
@comment GNU
@deftypefn Macro size_t obstack_chunk_size (struct obstack *@var{obstack-ptr})
This returns the chunk size of the given obstack.
@end deftypefn
Since this macro expands to an lvalue, you can specify a new chunk size by
assigning it a new value. Doing so does not affect the chunks already
allocated, but will change the size of chunks allocated for that particular
obstack in the future. It is unlikely to be useful to make the chunk size
smaller, but making it larger might improve efficiency if you are
allocating many objects whose size is comparable to the chunk size. Here
is how to do so cleanly:
@smallexample
if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size})
obstack_chunk_size (obstack_ptr) = @var{new-chunk-size};
@end smallexample
@node Summary of Obstacks
@subsubsection Summary of Obstack Macros
Here is a summary of all the macros associated with obstacks. Each
takes the address of an obstack (@code{struct obstack *}) as its first
argument.
@table @code
@item int obstack_init (struct obstack *@var{obstack-ptr})
Initialize use of an obstack. @xref{Creating Obstacks}.
@item int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size)
Initialize use of an obstack, with an initial chunk of
@var{chunk_size} bytes.
@item int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *))
Initialize use of an obstack, specifying intial chunk size, chunk
alignment, and memory allocation functions.
@item int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg)
Like @code{obstack_specify_allocation}, but specifying memory
allocation functions that take an extra first argument, @var{arg}.
@item void *obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size})
Allocate an object of @var{size} uninitialized bytes.
@xref{Allocation in an Obstack}.
@item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
Allocate an object of @var{size} bytes, with contents copied from
@var{address}. @xref{Allocation in an Obstack}.
@item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
Allocate an object of @var{size}+1 bytes, with @var{size} of them copied
from @var{address}, followed by a null character at the end.
@xref{Allocation in an Obstack}.
@item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
Free @var{object} (and everything allocated in the specified obstack
more recently than @var{object}). @xref{Freeing Obstack Objects}.
@item void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size})
Add @var{size} uninitialized bytes to a growing object.
@xref{Growing Objects}.
@item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
Add @var{size} bytes, copied from @var{address}, to a growing object.
@xref{Growing Objects}.
@item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
Add @var{size} bytes, copied from @var{address}, to a growing object,
and then add another byte containing a null character. @xref{Growing
Objects}.
@item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char})
Add one byte containing @var{data-char} to a growing object.
@xref{Growing Objects}.
@item void *obstack_finish (struct obstack *@var{obstack-ptr})
Finalize the object that is growing and return its permanent address.
@xref{Growing Objects}.
@item size_t obstack_object_size (struct obstack *@var{obstack-ptr})
Get the current size of the currently growing object. @xref{Growing
Objects}.
@item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size})
Add @var{size} uninitialized bytes to a growing object without checking
that there is enough room. @xref{Extra Fast Growing}.
@item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char})
Add one byte containing @var{data-char} to a growing object without
checking that there is enough room. @xref{Extra Fast Growing}.
@item size_t obstack_room (struct obstack *@var{obstack-ptr})
Get the amount of room now available for growing the current object.
@xref{Extra Fast Growing}.
@item size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr})
The mask used for aligning the beginning of an object. This is an
lvalue. @xref{Obstacks Data Alignment}.
@item size_t obstack_chunk_size (struct obstack *@var{obstack-ptr})
The size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}.
@item void *obstack_base (struct obstack *@var{obstack-ptr})
Tentative starting address of the currently growing object.
@xref{Status of an Obstack}.
@item void *obstack_next_free (struct obstack *@var{obstack-ptr})
Address just after the end of the currently growing object.
@xref{Status of an Obstack}.
@end table

788
libitm/libitm.texi Normal file
View File

@ -0,0 +1,788 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename libitm.info
@settitle GNU libitm
@c %**end of header
@copying
Copyright @copyright{} 2011-2022 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.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end copying
@ifinfo
@dircategory GNU Libraries
@direntry
* libitm: (libitm). GNU Transactional Memory Library
@end direntry
This manual documents the GNU Transactional Memory Library.
@insertcopying
@end ifinfo
@setchapternewpage odd
@titlepage
@title The GNU Transactional Memory Library
@page
@vskip 0pt plus 1filll
@comment For the @value{version-GCC} Version*
@sp 1
@insertcopying
@end titlepage
@summarycontents
@contents
@page
@node Top
@top Introduction
@cindex Introduction
This manual documents the usage and internals of libitm, the GNU Transactional
Memory Library. It provides transaction support for accesses to a process'
memory, enabling easy-to-use synchronization of accesses to shared memory by
several threads.
@comment
@comment When you add a new menu item, please keep the right hand
@comment aligned to the same column. Do not use tabs. This provides
@comment better formatting.
@comment
@menu
* Enabling libitm:: How to enable libitm for your applications.
* C/C++ Language Constructs for TM::
Notes on the language-level interface supported
by gcc.
* The libitm ABI:: Notes on the external ABI provided by libitm.
* Internals:: Notes on libitm's internal synchronization.
* GNU Free Documentation License::
How you can copy and share this manual.
* Library Index:: Index of this documentation.
@end menu
@c ---------------------------------------------------------------------
@c Enabling libitm
@c ---------------------------------------------------------------------
@node Enabling libitm
@chapter Enabling libitm
To activate support for TM in C/C++, the compile-time flag @option{-fgnu-tm}
must be specified. This enables TM language-level constructs such as
transaction statements (e.g., @code{__transaction_atomic}, @pxref{C/C++
Language Constructs for TM} for details).
@c ---------------------------------------------------------------------
@c C/C++ Language Constructs for TM
@c ---------------------------------------------------------------------
@node C/C++ Language Constructs for TM
@chapter C/C++ Language Constructs for TM
Transactions are supported in C++ and C in the form of transaction statements,
transaction expressions, and function transactions. In the following example,
both @code{a} and @code{b} will be read and the difference will be written to
@code{c}, all atomically and isolated from other transactions:
@example
__transaction_atomic @{ c = a - b; @}
@end example
Therefore, another thread can use the following code to concurrently update
@code{b} without ever causing @code{c} to hold a negative value (and without
having to use other synchronization constructs such as locks or C++11
atomics):
@example
__transaction_atomic @{ if (a > b) b++; @}
@end example
GCC follows the @uref{https://sites.google.com/site/tmforcplusplus/, Draft
Specification of Transactional Language Constructs for C++ (v1.1)} in its
implementation of transactions.
The precise semantics of transactions are defined in terms of the C++11/C11
memory model (see the specification). Roughly, transactions provide
synchronization guarantees that are similar to what would be guaranteed when
using a single global lock as a guard for all transactions. Note that like
other synchronization constructs in C/C++, transactions rely on a
data-race-free program (e.g., a nontransactional write that is concurrent
with a transactional read to the same memory location is a data race).
@c ---------------------------------------------------------------------
@c The libitm ABI
@c ---------------------------------------------------------------------
@node The libitm ABI
@chapter The libitm ABI
The ABI provided by libitm is basically equal to the Linux variant of Intel's
current TM ABI specification document (Revision 1.1, May 6 2009) but with the
differences listed in this chapter. It would be good if these changes would
eventually be merged into a future version of this specification. To ease
look-up, the following subsections mirror the structure of this specification.
@section [No changes] Objectives
@section [No changes] Non-objectives
@section Library design principles
@subsection [No changes] Calling conventions
@subsection [No changes] TM library algorithms
@subsection [No changes] Optimized load and store routines
@subsection [No changes] Aligned load and store routines
@subsection Data logging functions
The memory locations accessed with transactional loads and stores and the
memory locations whose values are logged must not overlap. This required
separation only extends to the scope of the execution of one transaction
including all the executions of all nested transactions.
The compiler must be consistent (within the scope of a single transaction)
about which memory locations are shared and which are not shared with other
threads (i.e., data must be accessed either transactionally or
nontransactionally). Otherwise, non-write-through TM algorithms would not work.
For memory locations on the stack, this requirement extends to only the
lifetime of the stack frame that the memory location belongs to (or the
lifetime of the transaction, whichever is shorter). Thus, memory that is
reused for several stack frames could be target of both data logging and
transactional accesses; however, this is harmless because these stack frames'
lifetimes will end before the transaction finishes.
@subsection [No changes] Scatter/gather calls
@subsection [No changes] Serial and irrevocable mode
@subsection [No changes] Transaction descriptor
@subsection Store allocation
There is no @code{getTransaction} function.
@subsection [No changes] Naming conventions
@subsection Function pointer encryption
Currently, this is not implemented.
@section Types and macros list
@code{_ITM_codeProperties} has changed, @pxref{txn-code-properties,,Starting a
transaction}.
@code{_ITM_srcLocation} is not used.
@section Function list
@subsection Initialization and finalization functions
These functions are not part of the ABI.
@subsection [No changes] Version checking
@subsection [No changes] Error reporting
@subsection [No changes] inTransaction call
@subsection State manipulation functions
There is no @code{getTransaction} function. Transaction identifiers for
nested transactions will be ordered but not necessarily sequential (i.e., for
a nested transaction's identifier @var{IN} and its enclosing transaction's
identifier @var{IE}, it is guaranteed that @math{IN >= IE}).
@subsection [No changes] Source locations
@subsection Starting a transaction
@subsubsection Transaction code properties
@anchor{txn-code-properties}
The bit @code{hasNoXMMUpdate} is instead called @code{hasNoVectorUpdate}.
Iff it is set, vector register save/restore is not necessary for any target
machine.
The @code{hasNoFloatUpdate} bit (@code{0x0010}) is new. Iff it is set, floating
point register save/restore is not necessary for any target machine.
@code{undoLogCode} is not supported and a fatal runtime error will be raised
if this bit is set. It is not properly defined in the ABI why barriers
other than undo logging are not present; Are they not necessary (e.g., a
transaction operating purely on thread-local data) or have they been omitted by
the compiler because it thinks that some kind of global synchronization
(e.g., serial mode) might perform better? The specification suggests that the
latter might be the case, but the former seems to be more useful.
The @code{readOnly} bit (@code{0x4000}) is new. @strong{TODO} Lexical or dynamic
scope?
@code{hasNoRetry} is not supported. If this bit is not set, but
@code{hasNoAbort} is set, the library can assume that transaction
rollback will not be requested.
It would be useful if the absence of externally-triggered rollbacks would be
reported for the dynamic scope as well, not just for the lexical scope
(@code{hasNoAbort}). Without this, a library cannot exploit this together
with flat nesting.
@code{exceptionBlock} is not supported because exception blocks are not used.
@subsubsection [No changes] Windows exception state
@subsubsection [No changes] Other machine state
@subsubsection [No changes] Results from beginTransaction
@subsection Aborting a transaction
@code{_ITM_rollbackTransaction} is not supported. @code{_ITM_abortTransaction}
is supported but the abort reasons @code{exceptionBlockAbort},
@code{TMConflict}, and @code{userRetry} are not supported. There are no
exception blocks in general, so the related cases also do not have to be
considered. To encode @code{__transaction_cancel [[outer]]}, compilers must
set the new @code{outerAbort} bit (@code{0x10}) additionally to the
@code{userAbort} bit in the abort reason.
@subsection Committing a transaction
The exception handling (EH) scheme is different. The Intel ABI requires the
@code{_ITM_tryCommitTransaction} function that will return even when the
commit failed and will have to be matched with calls to either
@code{_ITM_abortTransaction} or @code{_ITM_commitTransaction}. In contrast,
gcc relies on transactional wrappers for the functions of the Exception
Handling ABI and on one additional commit function (shown below). This allows
the TM to keep track of EH internally and thus it does not have to embed the
cleanup of EH state into the existing EH code in the program.
@code{_ITM_tryCommitTransaction} is not supported.
@code{_ITM_commitTransactionToId} is also not supported because the
propagation of thrown exceptions will not bypass commits of nested
transactions.
@example
void _ITM_commitTransactionEH(void *exc_ptr) ITM_REGPARM;
void *_ITM_cxa_allocate_exception (size_t);
void _ITM_cxa_free_exception (void *exc_ptr);
void _ITM_cxa_throw (void *obj, void *tinfo, void (*dest) (void *));
void *_ITM_cxa_begin_catch (void *exc_ptr);
void _ITM_cxa_end_catch (void);
@end example
The EH scheme changed in version 6 of GCC. Previously, the compiler
added a call to @code{_ITM_commitTransactionEH} to commit a transaction if
an exception could be in flight at this position in the code; @code{exc_ptr} is
the address of the current exception and must be non-zero. Now, the
compiler must catch all exceptions that are about to be thrown out of a
transaction and call @code{_ITM_commitTransactionEH} from the catch clause,
with @code{exc_ptr} being zero.
Note that the old EH scheme never worked completely in GCC's implementation;
libitm currently does not try to be compatible with the old scheme.
The @code{_ITM_cxa...} functions are transactional wrappers for the respective
@code{__cxa...} functions and must be called instead of these in transactional
code. @code{_ITM_cxa_free_exception} is new in GCC 6.
To support this EH scheme, libstdc++ needs to provide one additional function
(@code{_cxa_tm_cleanup}), which is used by the TM to clean up the exception
handling state while rolling back a transaction:
@example
void __cxa_tm_cleanup (void *unthrown_obj, void *cleanup_exc,
unsigned int caught_count);
@end example
Since GCC 6, @code{unthrown_obj} is not used anymore and always null;
prior to that, @code{unthrown_obj} is non-null if the program called
@code{__cxa_allocate_exception} for this exception but did not yet called
@code{__cxa_throw} for it. @code{cleanup_exc} is non-null if the program is
currently processing a cleanup along an exception path but has not caught this
exception yet. @code{caught_count} is the nesting depth of
@code{__cxa_begin_catch} within the transaction (which can be counted by the TM
using @code{_ITM_cxa_begin_catch} and @code{_ITM_cxa_end_catch});
@code{__cxa_tm_cleanup} then performs rollback by essentially performing
@code{__cxa_end_catch} that many times.
@subsection Exception handling support
Currently, there is no support for functionality like
@code{__transaction_cancel throw} as described in the C++ TM specification.
Supporting this should be possible with the EH scheme explained previously
because via the transactional wrappers for the EH ABI, the TM is able to
observe and intercept EH.
@subsection [No changes] Transition to serial--irrevocable mode
@subsection [No changes] Data transfer functions
@subsection [No changes] Transactional memory copies
@subsection Transactional versions of memmove
If either the source or destination memory region is to be accessed
nontransactionally, then source and destination regions must not be
overlapping. The respective @code{_ITM_memmove} functions are still
available but a fatal runtime error will be raised if such regions do overlap.
To support this functionality, the ABI would have to specify how the
intersection of the regions has to be accessed (i.e., transactionally or
nontransactionally).
@subsection [No changes] Transactional versions of memset
@subsection [No changes] Logging functions
@subsection User-registered commit and undo actions
Commit actions will get executed in the same order in which the respective
calls to @code{_ITM_addUserCommitAction} happened. Only
@code{_ITM_noTransactionId} is allowed as value for the
@code{resumingTransactionId} argument. Commit actions get executed after
privatization safety has been ensured.
Undo actions will get executed in reverse order compared to the order in which
the respective calls to @code{_ITM_addUserUndoAction} happened. The ordering of
undo actions w.r.t. the roll-back of other actions (e.g., data transfers or
memory allocations) is undefined.
@code{_ITM_getThreadnum} is not supported currently because its only purpose
is to provide a thread ID that matches some assumed performance tuning output,
but this output is not part of the ABI nor further defined by it.
@code{_ITM_dropReferences} is not supported currently because its semantics and
the intention behind it is not entirely clear. The
specification suggests that this function is necessary because of certain
orderings of data transfer undos and the releasing of memory regions (i.e.,
privatization). However, this ordering is never defined, nor is the ordering of
dropping references w.r.t. other events.
@subsection [New] Transactional indirect calls
Indirect calls (i.e., calls through a function pointer) within transactions
should execute the transactional clone of the original function (i.e., a clone
of the original that has been fully instrumented to use the TM runtime), if
such a clone is available. The runtime provides two functions to
register/deregister clone tables:
@example
struct clone_entry
@{
void *orig, *clone;
@};
void _ITM_registerTMCloneTable (clone_entry *table, size_t entries);
void _ITM_deregisterTMCloneTable (clone_entry *table);
@end example
Registered tables must be writable by the TM runtime, and must be live
throughout the life-time of the TM runtime.
@strong{TODO} The intention was always to drop the registration functions
entirely, and create a new ELF Phdr describing the linker-sorted table. Much
like what currently happens for @code{PT_GNU_EH_FRAME}.
This work kept getting bogged down in how to represent the @var{N} different
code generation variants. We clearly needed at least two---SW and HW
transactional clones---but there was always a suggestion of more variants for
different TM assumptions/invariants.
The compiler can then use two TM runtime functions to perform indirect calls in
transactions:
@example
void *_ITM_getTMCloneOrIrrevocable (void *function) ITM_REGPARM;
void *_ITM_getTMCloneSafe (void *function) ITM_REGPARM;
@end example
If there is a registered clone for supplied function, both will return a
pointer to the clone. If not, the first runtime function will attempt to switch
to serial--irrevocable mode and return the original pointer, whereas the second
will raise a fatal runtime error.
@subsection [New] Transactional dynamic memory management
@example
void *_ITM_malloc (size_t)
__attribute__((__malloc__)) ITM_PURE;
void *_ITM_calloc (size_t, size_t)
__attribute__((__malloc__)) ITM_PURE;
void _ITM_free (void *) ITM_PURE;
@end example
These functions are essentially transactional wrappers for @code{malloc},
@code{calloc}, and @code{free}. Within transactions, the compiler should
replace calls to the original functions with calls to the wrapper functions.
libitm also provides transactional clones of C++ memory management functions
such as global operator new and delete. They are part of libitm for historic
reasons but do not need to be part of this ABI.
@section [No changes] Future Enhancements to the ABI
@section Sample code
The code examples might not be correct w.r.t. the current version of the ABI,
especially everything related to exception handling.
@section [New] Memory model
The ABI should define a memory model and the ordering that is guaranteed for
data transfers and commit/undo actions, or at least refer to another memory
model that needs to be preserved. Without that, the compiler cannot ensure the
memory model specified on the level of the programming language (e.g., by the
C++ TM specification).
For example, if a transactional load is ordered before another load/store, then
the TM runtime must also ensure this ordering when accessing shared state. If
not, this might break the kind of publication safety used in the C++ TM
specification. Likewise, the TM runtime must ensure privatization safety.
@c ---------------------------------------------------------------------
@c Internals
@c ---------------------------------------------------------------------
@node Internals
@chapter Internals
@section TM methods and method groups
libitm supports several ways of synchronizing transactions with each other.
These TM methods (or TM algorithms) are implemented in the form of
subclasses of @code{abi_dispatch}, which provide methods for
transactional loads and stores as well as callbacks for rollback and commit.
All methods that are compatible with each other (i.e., that let concurrently
running transactions still synchronize correctly even if different methods
are used) belong to the same TM method group. Pointers to TM methods can be
obtained using the factory methods prefixed with @code{dispatch_} in
@file{libitm_i.h}. There are two special methods, @code{dispatch_serial} and
@code{dispatch_serialirr}, that are compatible with all methods because they
run transactions completely in serial mode.
@subsection TM method life cycle
The state of TM methods does not change after construction, but they do alter
the state of transactions that use this method. However, because
per-transaction data gets used by several methods, @code{gtm_thread} is
responsible for setting an initial state that is useful for all methods.
After that, methods are responsible for resetting/clearing this state on each
rollback or commit (of outermost transactions), so that the transaction
executed next is not affected by the previous transaction.
There is also global state associated with each method group, which is
initialized and shut down (@code{method_group::init()} and @code{fini()})
when switching between method groups (see @file{retry.cc}).
@subsection Selecting the default method
The default method that libitm uses for freshly started transactions (but
not necessarily for restarted transactions) can be set via an environment
variable (@env{ITM_DEFAULT_METHOD}), whose value should be equal to the name
of one of the factory methods returning abi_dispatch subclasses but without
the "dispatch_" prefix (e.g., "serialirr" instead of
@code{GTM::dispatch_serialirr()}).
Note that this environment variable is only a hint for libitm and might not
be supported in the future.
@section Nesting: flat vs. closed
We support two different kinds of nesting of transactions. In the case of
@emph{flat nesting}, the nesting structure is flattened and all nested
transactions are subsumed by the enclosing transaction. In contrast,
with @emph{closed nesting}, nested transactions that have not yet committed
can be rolled back separately from the enclosing transactions; when they
commit, they are subsumed by the enclosing transaction, and their effects
will be finally committed when the outermost transaction commits.
@emph{Open nesting} (where nested transactions can commit independently of the
enclosing transactions) are not supported.
Flat nesting is the default nesting mode, but closed nesting is supported and
used when transactions contain user-controlled aborts
(@code{__transaction_cancel} statements). We assume that user-controlled
aborts are rare in typical code and used mostly in exceptional situations.
Thus, it makes more sense to use flat nesting by default to avoid the
performance overhead of the additional checkpoints required for closed
nesting. User-controlled aborts will correctly abort the innermost enclosing
transaction, whereas the whole (i.e., outermost) transaction will be restarted
otherwise (e.g., when a transaction encounters data conflicts during
optimistic execution).
@section Locking conventions
This section documents the locking scheme and rules for all uses of locking
in libitm. We have to support serial(-irrevocable) mode, which is implemented
using a global lock as explained next (called the @emph{serial lock}). To
simplify the overall design, we use the same lock as catch-all locking
mechanism for other infrequent tasks such as (de)registering clone tables or
threads. Besides the serial lock, there are @emph{per-method-group locks} that
are managed by specific method groups (i.e., groups of similar TM concurrency
control algorithms), and lock-like constructs for quiescence-based operations
such as ensuring privatization safety.
Thus, the actions that participate in the libitm-internal locking are either
@emph{active transactions} that do not run in serial mode, @emph{serial
transactions} (which (are about to) run in serial mode), and management tasks
that do not execute within a transaction but have acquired the serial mode
like a serial transaction would do (e.g., to be able to register threads with
libitm). Transactions become active as soon as they have successfully used the
serial lock to announce this globally (@pxref{serial-lock-impl,,Serial lock
implementation}). Likewise, transactions become serial transactions as soon as
they have acquired the exclusive rights provided by the serial lock (i.e.,
serial mode, which also means that there are no other concurrent active or
serial transactions). Note that active transactions can become serial
transactions when they enter serial mode during the runtime of the
transaction.
@subsection State-to-lock mapping
Application data is protected by the serial lock if there is a serial
transaction and no concurrently running active transaction (i.e., non-serial).
Otherwise, application data is protected by the currently selected method
group, which might use per-method-group locks or other mechanisms. Also note
that application data that is about to be privatized might not be allowed to be
accessed by nontransactional code until privatization safety has been ensured;
the details of this are handled by the current method group.
libitm-internal state is either protected by the serial lock or accessed
through custom concurrent code. The latter applies to the public/shared part
of a transaction object and most typical method-group-specific state.
The former category (protected by the serial lock) includes:
@itemize @bullet
@item The list of active threads that have used transactions.
@item The tables that map functions to their transactional clones.
@item The current selection of which method group to use.
@item Some method-group-specific data, or invariants of this data. For example,
resetting a method group to its initial state is handled by switching to the
same method group, so the serial lock protects such resetting as well.
@end itemize
In general, such state is immutable whenever there exists an active
(non-serial) transaction. If there is no active transaction, a serial
transaction (or a thread that is not currently executing a transaction but has
acquired the serial lock) is allowed to modify this state (but must of course
be careful to not surprise the current method group's implementation with such
modifications).
@subsection Lock acquisition order
To prevent deadlocks, locks acquisition must happen in a globally agreed-upon
order. Note that this applies to other forms of blocking too, but does not
necessarily apply to lock acquisitions that do not block (e.g., trylock()
calls that do not get retried forever). Note that serial transactions are
never return back to active transactions until the transaction has committed.
Likewise, active transactions stay active until they have committed.
Per-method-group locks are typically also not released before commit.
Lock acquisition / blocking rules:
@itemize @bullet
@item Transactions must become active or serial before they are allowed to
use method-group-specific locks or blocking (i.e., the serial lock must be
acquired before those other locks, either in serial or nonserial mode).
@item Any number of threads that do not currently run active transactions can
block while trying to get the serial lock in exclusive mode. Note that active
transactions must not block when trying to upgrade to serial mode unless there
is no other transaction that is trying that (the latter is ensured by the
serial lock implementation.
@item Method groups must prevent deadlocks on their locks. In particular, they
must also be prepared for another active transaction that has acquired
method-group-specific locks but is blocked during an attempt to upgrade to
being a serial transaction. See below for details.
@item Serial transactions can acquire method-group-specific locks because there
will be no other active nor serial transaction.
@end itemize
There is no single rule for per-method-group blocking because this depends on
when a TM method might acquire locks. If no active transaction can upgrade to
being a serial transaction after it has acquired per-method-group locks (e.g.,
when those locks are only acquired during an attempt to commit), then the TM
method does not need to consider a potential deadlock due to serial mode.
If there can be upgrades to serial mode after the acquisition of
per-method-group locks, then TM methods need to avoid those deadlocks:
@itemize @bullet
@item When upgrading to a serial transaction, after acquiring exclusive rights
to the serial lock but before waiting for concurrent active transactions to
finish (@pxref{serial-lock-impl,,Serial lock implementation} for details),
we have to wake up all active transactions waiting on the upgrader's
per-method-group locks.
@item Active transactions blocking on per-method-group locks need to check the
serial lock and abort if there is a pending serial transaction.
@item Lost wake-ups have to be prevented (e.g., by changing a bit in each
per-method-group lock before doing the wake-up, and only blocking on this lock
using a futex if this bit is not group).
@end itemize
@strong{TODO}: Can reuse serial lock for gl-*? And if we can, does it make
sense to introduce further complexity in the serial lock? For gl-*, we can
really only avoid an abort if we do -wb and -vbv.
@subsection Serial lock implementation
@anchor{serial-lock-impl}
The serial lock implementation is optimized towards assuming that serial
transactions are infrequent and not the common case. However, the performance
of entering serial mode can matter because when only few transactions are run
concurrently or if there are few threads, then it can be efficient to run
transactions serially.
The serial lock is similar to a multi-reader-single-writer lock in that there
can be several active transactions but only one serial transaction. However,
we do want to avoid contention (in the lock implementation) between active
transactions, so we split up the reader side of the lock into per-transaction
flags that are true iff the transaction is active. The exclusive writer side
remains a shared single flag, which is acquired using a CAS, for example.
On the fast-path, the serial lock then works similar to Dekker's algorithm but
with several reader flags that a serial transaction would have to check.
A serial transaction thus requires a list of all threads with potentially
active transactions; we can use the serial lock itself to protect this list
(i.e., only threads that have acquired the serial lock can modify this list).
We want starvation-freedom for the serial lock to allow for using it to ensure
progress for potentially starved transactions (@pxref{progress-guarantees,,
Progress Guarantees} for details). However, this is currently not enforced by
the implementation of the serial lock.
Here is pseudo-code for the read/write fast paths of acquiring the serial
lock (read-to-write upgrade is similar to write_lock:
@example
// read_lock:
tx->shared_state |= active;
__sync_synchronize(); // or STLD membar, or C++0x seq-cst fence
while (!serial_lock.exclusive)
if (spinning_for_too_long) goto slowpath;
// write_lock:
if (CAS(&serial_lock.exclusive, 0, this) != 0)
goto slowpath; // writer-writer contention
// need a membar here, but CAS already has full membar semantics
bool need_blocking = false;
for (t: all txns)
@{
for (;t->shared_state & active;)
if (spinning_for_too_long) @{ need_blocking = true; break; @}
@}
if (need_blocking) goto slowpath;
@end example
Releasing a lock in this spin-lock version then just consists of resetting
@code{tx->shared_state} to inactive or clearing @code{serial_lock.exclusive}.
However, we can't rely on a pure spinlock because we need to get the OS
involved at some time (e.g., when there are more threads than CPUs to run on).
Therefore, the real implementation falls back to a blocking slow path, either
based on pthread mutexes or Linux futexes.
@subsection Reentrancy
libitm has to consider the following cases of reentrancy:
@itemize @bullet
@item Transaction calls unsafe code that starts a new transaction: The outer
transaction will become a serial transaction before executing unsafe code.
Therefore, nesting within serial transactions must work, even if the nested
transaction is called from within uninstrumented code.
@item Transaction calls either a transactional wrapper or safe code, which in
turn starts a new transaction: It is not yet defined in the specification
whether this is allowed. Thus, it is undefined whether libitm supports this.
@item Code that starts new transactions might be called from within any part
of libitm: This kind of reentrancy would likely be rather complex and can
probably be avoided. Therefore, it is not supported.
@end itemize
@subsection Privatization safety
Privatization safety is ensured by libitm using a quiescence-based approach.
Basically, a privatizing transaction waits until all concurrent active
transactions will either have finished (are not active anymore) or operate on
a sufficiently recent snapshot to not access the privatized data anymore. This
happens after the privatizing transaction has stopped being an active
transaction, so waiting for quiescence does not contribute to deadlocks.
In method groups that need to ensure publication safety explicitly, active
transactions maintain a flag or timestamp in the public/shared part of the
transaction descriptor. Before blocking, privatizers need to let the other
transactions know that they should wake up the privatizer.
@strong{TODO} Ho to implement the waiters? Should those flags be
per-transaction or at a central place? We want to avoid one wake/wait call
per active transactions, so we might want to use either a tree or combining
to reduce the syscall overhead, or rather spin for a long amount of time
instead of doing blocking. Also, it would be good if only the last transaction
that the privatizer waits for would do the wake-up.
@subsection Progress guarantees
@anchor{progress-guarantees}
Transactions that do not make progress when using the current TM method will
eventually try to execute in serial mode. Thus, the serial lock's progress
guarantees determine the progress guarantees of the whole TM. Obviously, we at
least need deadlock-freedom for the serial lock, but it would also be good to
provide starvation-freedom (informally, all threads will finish executing a
transaction eventually iff they get enough cycles).
However, the scheduling of transactions (e.g., thread scheduling by the OS)
also affects the handling of progress guarantees by the TM. First, the TM
can only guarantee deadlock-freedom if threads do not get stopped. Likewise,
low-priority threads can starve if they do not get scheduled when other
high-priority threads get those cycles instead.
If all threads get scheduled eventually, correct lock implementations will
provide deadlock-freedom, but might not provide starvation-freedom. We can
either enforce the latter in the TM's lock implementation, or assume that
the scheduling is sufficiently random to yield a probabilistic guarantee that
no thread will starve (because eventually, a transaction will encounter a
scheduling that will allow it to run). This can indeed work well in practice
but is not necessarily guaranteed to work (e.g., simple spin locks can be
pretty efficient).
Because enforcing stronger progress guarantees in the TM has a higher runtime
overhead, we focus on deadlock-freedom right now and assume that the threads
will get scheduled eventually by the OS (but don't consider threads with
different priorities). We should support starvation-freedom for serial
transactions in the future. Everything beyond that is highly related to proper
contention management across all of the TM (including with TM method to
choose), and is future work.
@strong{TODO} Handling thread priorities: We want to avoid priority inversion
but it's unclear how often that actually matters in practice. Workloads that
have threads with different priorities will likely also require lower latency
or higher throughput for high-priority threads. Therefore, it probably makes
not that much sense (except for eventual progress guarantees) to use
priority inheritance until the TM has priority-aware contention management.
@c ---------------------------------------------------------------------
@c GNU Free Documentation License
@c ---------------------------------------------------------------------
@include fdl.texi
@c ---------------------------------------------------------------------
@c Index
@c ---------------------------------------------------------------------
@node Library Index
@unnumbered Library Index
@printindex cp
@bye

392
libquadmath/libquadmath.texi Normal file
View File

@ -0,0 +1,392 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename libquadmath.info
@settitle GCC libquadmath
@c %**end of header
@copying
Copyright @copyright{} 2010-2022 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled ``GNU Free Documentation
License.''
(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.
@end quotation
@end copying
@ifinfo
@dircategory GNU Libraries
@direntry
* libquadmath: (libquadmath). GCC Quad-Precision Math Library
@end direntry
This manual documents the GCC Quad-Precision Math Library API.
Published by the Free Software Foundation
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301 USA
@insertcopying
@end ifinfo
@setchapternewpage odd
@titlepage
@title The GCC Quad-Precision Math Library
@page
@vskip 0pt plus 1filll
@comment For the @value{version-GCC} Version*
@sp 1
Published by the Free Software Foundation @*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301, USA@*
@sp 1
@insertcopying
@end titlepage
@summarycontents
@contents
@page
@node Top
@top Introduction
@cindex Introduction
This manual documents the usage of libquadmath, the GCC Quad-Precision
Math Library Application Programming Interface (API).
@comment
@comment When you add a new menu item, please keep the right hand
@comment aligned to the same column. Do not use tabs. This provides
@comment better formatting.
@comment
@menu
* Typedef and constants:: Defined data types and constants
* Math Library Routines:: The Libquadmath math runtime application
programming interface.
* I/O Library Routines:: The Libquadmath I/O runtime application
programming interface.
* GNU Free Documentation License::
How you can copy and share this manual.
* Reporting Bugs:: How to report bugs in GCC Libquadmath.
@c * Index:: Index of this documentation.
@end menu
@c ---------------------------------------------------------------------
@c Defined macros
@c ---------------------------------------------------------------------
@node Typedef and constants
@chapter Typedef and constants
The following data type has been defined via @code{typedef}.
@table @asis
@item @code{__complex128}: @code{__float128}-based complex number
@end table
The following macros are defined, which give the numeric limits of the
@code{__float128} data type.
@table @asis
@item @code{FLT128_MAX}: largest finite number
@item @code{FLT128_MIN}: smallest positive number with full precision
@item @code{FLT128_EPSILON}: difference between 1 and the next larger
representable number
@item @code{FLT128_DENORM_MIN}: smallest positive denormalized number
@item @code{FLT128_MANT_DIG}: number of digits in the mantissa (bit precision)
@item @code{FLT128_MIN_EXP}: maximal negative exponent
@item @code{FLT128_MAX_EXP}: maximal positive exponent
@item @code{FLT128_DIG}: number of decimal digits in the mantissa
@item @code{FLT128_MIN_10_EXP}: maximal negative decimal exponent
@item @code{FLT128_MAX_10_EXP}: maximal positive decimal exponent
@end table
The following mathematical constants of type @code{__float128} are defined.
@table @asis
@item @code{M_Eq}: the constant e (Euler's number)
@item @code{M_LOG2Eq}: binary logarithm of 2
@item @code{M_LOG10Eq}: common, decimal logarithm of 2
@item @code{M_LN2q}: natural logarithm of 2
@item @code{M_LN10q}: natural logarithm of 10
@item @code{M_PIq}: pi
@item @code{M_PI_2q}: pi divided by two
@item @code{M_PI_4q}: pi divided by four
@item @code{M_1_PIq}: one over pi
@item @code{M_2_PIq}: one over two pi
@item @code{M_2_SQRTPIq}: two over square root of pi
@item @code{M_SQRT2q}: square root of 2
@item @code{M_SQRT1_2q}: one over square root of 2
@end table
@c ---------------------------------------------------------------------
@c Math routines
@c ---------------------------------------------------------------------
@node Math Library Routines
@chapter Math Library Routines
The following mathematical functions are available:
@table @asis
@item @code{acosq}: arc cosine function
@item @code{acoshq}: inverse hyperbolic cosine function
@item @code{asinq}: arc sine function
@item @code{asinhq}: inverse hyperbolic sine function
@item @code{atanq}: arc tangent function
@item @code{atanhq}: inverse hyperbolic tangent function
@item @code{atan2q}: arc tangent function
@item @code{cbrtq}: cube root function
@item @code{ceilq}: ceiling value function
@item @code{copysignq}: copy sign of a number
@item @code{coshq}: hyperbolic cosine function
@item @code{cosq}: cosine function
@item @code{erfq}: error function
@item @code{erfcq}: complementary error function
@item @code{exp2q}: base 2 exponential function
@item @code{expq}: exponential function
@item @code{expm1q}: exponential minus 1 function
@need 800
@item @code{fabsq}: absolute value function
@item @code{fdimq}: positive difference function
@item @code{finiteq}: check finiteness of value
@item @code{floorq}: floor value function
@item @code{fmaq}: fused multiply and add
@item @code{fmaxq}: determine maximum of two values
@item @code{fminq}: determine minimum of two values
@item @code{fmodq}: remainder value function
@item @code{frexpq}: extract mantissa and exponent
@item @code{hypotq}: Eucledian distance function
@item @code{ilogbq}: get exponent of the value
@item @code{isinfq}: check for infinity
@item @code{isnanq}: check for not a number
@item @code{issignalingq}: check for signaling not a number
@item @code{j0q}: Bessel function of the first kind, first order
@item @code{j1q}: Bessel function of the first kind, second order
@item @code{jnq}: Bessel function of the first kind, @var{n}-th order
@item @code{ldexpq}: load exponent of the value
@item @code{lgammaq}: logarithmic gamma function
@item @code{llrintq}: round to nearest integer value
@item @code{llroundq}: round to nearest integer value away from zero
@item @code{logbq}: get exponent of the value
@item @code{logq}: natural logarithm function
@item @code{log10q}: base 10 logarithm function
@item @code{log1pq}: compute natural logarithm of the value plus one
@item @code{log2q}: base 2 logarithm function
@need 800
@item @code{lrintq}: round to nearest integer value
@item @code{lroundq}: round to nearest integer value away from zero
@item @code{modfq}: decompose the floating-point number
@item @code{nanq}: return quiet NaN
@item @code{nearbyintq}: round to nearest integer
@item @code{nextafterq}: next representable floating-point number
@item @code{powq}: power function
@item @code{remainderq}: remainder function
@item @code{remquoq}: remainder and part of quotient
@item @code{rintq}: round-to-nearest integral value
@item @code{roundq}: round-to-nearest integral value, return @code{__float128}
@item @code{scalblnq}: compute exponent using @code{FLT_RADIX}
@item @code{scalbnq}: compute exponent using @code{FLT_RADIX}
@item @code{signbitq}: return sign bit
@item @code{sincosq}: calculate sine and cosine simultaneously
@item @code{sinhq}: hyperbolic sine function
@item @code{sinq}: sine function
@item @code{sqrtq}: square root function
@item @code{tanq}: tangent function
@item @code{tanhq}: hyperbolic tangent function
@need 800
@item @code{tgammaq}: true gamma function
@item @code{truncq}: round to integer, towards zero
@item @code{y0q}: Bessel function of the second kind, first order
@item @code{y1q}: Bessel function of the second kind, second order
@item @code{ynq}: Bessel function of the second kind, @var{n}-th order
@item @code{cabsq} complex absolute value function
@item @code{cargq}: calculate the argument
@item @code{cimagq} imaginary part of complex number
@item @code{crealq}: real part of complex number
@item @code{cacoshq}: complex arc hyperbolic cosine function
@item @code{cacosq}: complex arc cosine function
@item @code{casinhq}: complex arc hyperbolic sine function
@item @code{casinq}: complex arc sine function
@item @code{catanhq}: complex arc hyperbolic tangent function
@item @code{catanq}: complex arc tangent function
@item @code{ccosq} complex cosine function:
@item @code{ccoshq}: complex hyperbolic cosine function
@item @code{cexpq}: complex exponential function
@need 800
@item @code{cexpiq}: computes the exponential function of ``i'' times a
real value
@item @code{clogq}: complex natural logarithm
@item @code{clog10q}: complex base 10 logarithm
@item @code{conjq}: complex conjugate function
@item @code{cpowq}: complex power function
@item @code{cprojq}: project into Riemann Sphere
@item @code{csinq}: complex sine function
@item @code{csinhq}: complex hyperbolic sine function
@item @code{csqrtq}: complex square root
@item @code{ctanq}: complex tangent function
@item @code{ctanhq}: complex hyperbolic tangent function
@end table
@c ---------------------------------------------------------------------
@c I/O routines
@c ---------------------------------------------------------------------
@node I/O Library Routines
@chapter I/O Library Routines
@menu
* @code{strtoflt128}: strtoflt128, Convert from string
* @code{quadmath_snprintf}: quadmath_snprintf, Convert to string
@end menu
@node strtoflt128
@section @code{strtoflt128} --- Convert from string
The function @code{strtoflt128} converts a string into a
@code{__float128} number.
@table @asis
@item Syntax
@code{__float128 strtoflt128 (const char *s, char **sp)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{s} @tab input string
@item @var{sp} @tab the address of the next character in the string
@end multitable
The argument @var{sp} contains, if not @code{NULL}, the address of the
next character following the parts of the string, which have been read.
@item Example
@smallexample
#include <quadmath.h>
int main ()
@{
__float128 r;
r = strtoflt128 ("1.2345678", NULL);
return 0;
@}
@end smallexample
@end table
@node quadmath_snprintf
@section @code{quadmath_snprintf} --- Convert to string
The function @code{quadmath_snprintf} converts a @code{__float128} floating-point
number into a string. It is a specialized alternative to @code{snprintf}, where
the format string is restricted to a single conversion specifier with @code{Q}
modifier and conversion specifier @code{e}, @code{E}, @code{f}, @code{F}, @code{g},
@code{G}, @code{a} or @code{A}, with no extra characters before or after the
conversion specifier. The @code{%m$} or @code{*m$} style must not be used in
the format.
@table @asis
@item Syntax
@code{int quadmath_snprintf (char *s, size_t size, const char *format, ...)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{s} @tab output string
@item @var{size} @tab byte size of the string, including trailing NUL
@item @var{format} @tab conversion specifier string
@end multitable
@item Note
On some targets when supported by the C library hooks are installed
for @code{printf} family of functions, so that @code{printf ("%Qe", 1.2Q);}
etc.@: works too.
@item Example
@smallexample
#include <quadmath.h>
#include <stdlib.h>
#include <stdio.h>
int main ()
@{
__float128 r;
int prec = 20;
int width = 46;
char buf[128];
r = 2.0q;
r = sqrtq (r);
int n = quadmath_snprintf (buf, sizeof buf, "%+-#*.20Qe", width, r);
if ((size_t) n < sizeof buf)
printf ("%s\n", buf);
/* Prints: +1.41421356237309504880e+00 */
quadmath_snprintf (buf, sizeof buf, "%Qa", r);
if ((size_t) n < sizeof buf)
printf ("%s\n", buf);
/* Prints: 0x1.6a09e667f3bcc908b2fb1366ea96p+0 */
n = quadmath_snprintf (NULL, 0, "%+-#46.*Qe", prec, r);
if (n > -1)
@{
char *str = malloc (n + 1);
if (str)
@{
quadmath_snprintf (str, n + 1, "%+-#46.*Qe", prec, r);
printf ("%s\n", str);
/* Prints: +1.41421356237309504880e+00 */
@}
free (str);
@}
return 0;
@}
@end smallexample
@end table
@c ---------------------------------------------------------------------
@c GNU Free Documentation License
@c ---------------------------------------------------------------------
@include fdl.texi
@c ---------------------------------------------------------------------
@c Reporting Bugs
@c ---------------------------------------------------------------------
@c For BUGURL
@include libquadmath-vers.texi
@node Reporting Bugs
@chapter Reporting Bugs
Bugs in the GCC Quad-Precision Math Library implementation should be
reported via @value{BUGURL}.
@c ---------------------------------------------------------------------
@c Index
@c ---------------------------------------------------------------------
@c @node Index
@c @unnumbered Index
@c
@c @printindex cp
@bye