diff options
Diffstat (limited to 'contrib/gcc/doc')
-rw-r--r-- | contrib/gcc/doc/c-tree.texi | 4 | ||||
-rw-r--r-- | contrib/gcc/doc/compat.texi | 115 | ||||
-rw-r--r-- | contrib/gcc/doc/cppopts.texi | 4 | ||||
-rw-r--r-- | contrib/gcc/doc/extend.texi | 22 | ||||
-rw-r--r-- | contrib/gcc/doc/gcc.texi | 2 | ||||
-rw-r--r-- | contrib/gcc/doc/invoke.texi | 66 | ||||
-rw-r--r-- | contrib/gcc/doc/makefile.texi | 4 | ||||
-rw-r--r-- | contrib/gcc/doc/rtl.texi | 8 | ||||
-rw-r--r-- | contrib/gcc/doc/standards.texi | 18 | ||||
-rw-r--r-- | contrib/gcc/doc/tm.texi | 9 | ||||
-rw-r--r-- | contrib/gcc/doc/trouble.texi | 10 |
11 files changed, 211 insertions, 51 deletions
diff --git a/contrib/gcc/doc/c-tree.texi b/contrib/gcc/doc/c-tree.texi index 0e821e5..35da90a 100644 --- a/contrib/gcc/doc/c-tree.texi +++ b/contrib/gcc/doc/c-tree.texi @@ -1203,11 +1203,11 @@ Then, if @code{THUNK_VCALL_OFFSET} (an @code{INTEGER_CST}) is nonzero the adjusted @code{this} pointer must be adjusted again. The complete calculation is given by the following pseudo-code: -@example +@smallexample this += THUNK_DELTA if (THUNK_VCALL_OFFSET) this += (*((ptrdiff_t **) this))[THUNK_VCALL_OFFSET] -@end example +@end smallexample Finally, the thunk should jump to the location given by @code{DECL_INITIAL}; this will always be an expression for the diff --git a/contrib/gcc/doc/compat.texi b/contrib/gcc/doc/compat.texi new file mode 100644 index 0000000..3e4ef89 --- /dev/null +++ b/contrib/gcc/doc/compat.texi @@ -0,0 +1,115 @@ +@c Copyright (C) 2002 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 @code{-Wabi} switch warns when G++ generates code that is +probably not compatible with the C++ ABI@. diff --git a/contrib/gcc/doc/cppopts.texi b/contrib/gcc/doc/cppopts.texi index 463403e..308e989 100644 --- a/contrib/gcc/doc/cppopts.texi +++ b/contrib/gcc/doc/cppopts.texi @@ -541,10 +541,10 @@ standard-conforming modes it converts them. See the @option{-std} and The nine trigraphs and their replacements are -@example +@smallexample Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- Replacement: [ ] @{ @} # \ ^ | ~ -@end example +@end smallexample @end ifclear @item -remap diff --git a/contrib/gcc/doc/extend.texi b/contrib/gcc/doc/extend.texi index 4a33eea..79eea70 100644 --- a/contrib/gcc/doc/extend.texi +++ b/contrib/gcc/doc/extend.texi @@ -739,7 +739,7 @@ GCC implements taking the address of a nested function using a technique called @dfn{trampolines}. A paper describing them is available as @noindent -@uref{http://people.debian.org/~karlheg/Usenix88-lexic.pdf}. +@uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}. A nested function can jump to a label inherited from a containing function, provided the label was explicitly declared in the containing @@ -1396,9 +1396,9 @@ variable number of arguments much as a function can. The syntax for defining the macro is similar to that of a function. Here is an example: -@example +@smallexample #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) -@end example +@end smallexample Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of such a macro, it represents the zero or more tokens until the closing @@ -1437,9 +1437,9 @@ string. To help solve this problem, CPP behaves specially for variable arguments used with the token paste operator, @samp{##}. If instead you write -@example +@smallexample #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) -@end example +@end smallexample and if the variable arguments are omitted or empty, the @samp{##} operator causes the preprocessor to remove the comma before it. If you @@ -1749,9 +1749,9 @@ nested subobject to initialize; the list is taken relative to the subobject corresponding to the closest surrounding brace pair. For example, with the @samp{struct point} declaration above: -@example +@smallexample struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; -@end example +@end smallexample @noindent If the same field is initialized multiple times, it will have value from @@ -6749,10 +6749,10 @@ inclusive. Lower numbers indicate a higher priority. In the following example, @code{A} would normally be created before @code{B}, but the @code{init_priority} attribute has reversed that order: -@example +@smallexample Some_Class A __attribute__ ((init_priority (2000))); Some_Class B __attribute__ ((init_priority (543))); -@end example +@end smallexample @noindent Note that the particular values of @var{priority} do not matter; only their @@ -6778,7 +6778,7 @@ appropriately. However, if C++ code only needs to execute destructors when Java exceptions are thrown through it, GCC will guess incorrectly. Sample problematic code is: -@example +@smallexample struct S @{ ~S(); @}; extern void bar(); // is written in Java, and may throw exceptions void foo() @@ -6786,7 +6786,7 @@ Sample problematic code is: S s; bar(); @} -@end example +@end smallexample @noindent The usual effect of an incorrect guess is a link failure, complaining of diff --git a/contrib/gcc/doc/gcc.texi b/contrib/gcc/doc/gcc.texi index 4af8694..fe51216 100644 --- a/contrib/gcc/doc/gcc.texi +++ b/contrib/gcc/doc/gcc.texi @@ -164,6 +164,7 @@ Introduction, gccint, GNU Compiler Collection (GCC) Internals}. * 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:: gcov: a GCC test coverage program. * Trouble:: If you have trouble using GCC. * Bugs:: How, why and where to report bugs. @@ -188,6 +189,7 @@ Introduction, gccint, GNU Compiler Collection (GCC) Internals}. @include invoke.texi @include extend.texi @include objc.texi +@include compat.texi @include gcov.texi @include trouble.texi @include bugreport.texi diff --git a/contrib/gcc/doc/invoke.texi b/contrib/gcc/doc/invoke.texi index a3b53ed..d60d6fc 100644 --- a/contrib/gcc/doc/invoke.texi +++ b/contrib/gcc/doc/invoke.texi @@ -169,7 +169,7 @@ in the following sections. -fallow-single-precision -fcond-mismatch @gol -fsigned-bitfields -fsigned-char @gol -funsigned-bitfields -funsigned-char @gol --fwritable-strings -fshort-wchar} +-fwritable-strings} @item C++ Language Options @xref{C++ Dialect Options,,Options Controlling C++ Dialect}. @@ -279,8 +279,8 @@ in the following sections. -frerun-cse-after-loop -frerun-loop-opt @gol -fschedule-insns -fschedule-insns2 @gol -fsingle-precision-constant -fssa -fssa-ccp -fssa-dce @gol --fstrength-reduce -fstrict-aliasing -fthread-jumps -ftrapv @gol --funroll-all-loops -funroll-loops @gol +-fstrength-reduce -fstrict-aliasing -fthread-jumps @gol +-ftrapv -funroll-all-loops -funroll-loops @gol --param @var{name}=@var{value} -O -O0 -O1 -O2 -O3 -Os} @@ -444,7 +444,7 @@ in the following sections. -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol -mcall-aix -mcall-sysv -mcall-netbsd @gol --maix-struct-return -msvr4-struct-return +-maix-struct-return -msvr4-struct-return @gol -mabi=altivec -mabi=no-altivec @gol -mprototype -mno-prototype @gol -msim -mmvme -mads -myellowknife -memb -msdata @gol @@ -610,8 +610,8 @@ in the following sections. @emph{D30V Options} @gccoptlist{ --mextmem -mextmemory -monchip -mno-asm-optimize -masm-optimize @gol --mbranch-cost=@var{n} -mcond-exec=@var{n}} +-mextmem -mextmemory -monchip -mno-asm-optimize @gol +-masm-optimize -mbranch-cost=@var{n} -mcond-exec=@var{n}} @emph{S/390 and zSeries Options} @gccoptlist{ @@ -670,7 +670,7 @@ in the following sections. -fno-common -fno-ident -fno-gnu-linker @gol -fpcc-struct-return -fpic -fPIC @gol -freg-struct-return -fshared-data -fshort-enums @gol --fshort-double -fvolatile @gol +-fshort-double -fshort-wchar -fvolatile @gol -fvolatile-global -fvolatile-static @gol -fverbose-asm -fpack-struct -fstack-check @gol -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol @@ -1297,12 +1297,6 @@ than double precision. If you must use @option{-traditional}, but want to use single precision operations when the operands are single precision, use this option. This option has no effect when compiling with ISO or GNU C conventions (the default). - -@item -fshort-wchar -@opindex fshort-wchar -Override the underlying type for @samp{wchar_t} to be @samp{short -unsigned int} instead of the default for the target. This option is -useful for building programs to run under WINE@. @end table @node C++ Dialect Options @@ -9716,7 +9710,8 @@ unwinding from asynchronous events (such as debugger or garbage collector). Return ``short'' @code{struct} and @code{union} values in memory like longer ones, rather than in registers. This convention is less efficient, but it has the advantage of allowing intercallability between -GCC-compiled files and files compiled with other compilers. +GCC-compiled files and files compiled with other compilers, particularly +the Portable C Compiler (pcc). The precise convention for returning structures in memory depends on the target configuration macros. @@ -9724,6 +9719,11 @@ on the target configuration macros. Short structures and unions are those whose size and alignment match that of some integer type. +@strong{Warning:} code compiled with the @option{-fpcc-struct-return} +switch is not binary compatible with code compiled with the +@option{-freg-struct-return} switch. +Use it to conform to a non-default application binary interface. + @item -freg-struct-return @opindex freg-struct-return Return @code{struct} and @code{union} values in registers when possible. @@ -9737,16 +9737,39 @@ defaults to @option{-fpcc-struct-return}, except on targets where GCC is the principal compiler. In those cases, we can choose the standard, and we chose the more efficient register return alternative. +@strong{Warning:} code compiled with the @option{-freg-struct-return} +switch is not binary compatible with code compiled with the +@option{-fpcc-struct-return} switch. +Use it to conform to a non-default application binary interface. + @item -fshort-enums @opindex fshort-enums Allocate to an @code{enum} type only as many bytes as it needs for the declared range of possible values. Specifically, the @code{enum} type will be equivalent to the smallest integer type which has enough room. +@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate +code that is not binary compatible with code generated without that switch. +Use it to conform to a non-default application binary interface. + @item -fshort-double @opindex fshort-double Use the same size for @code{double} as for @code{float}. +@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate +code that is not binary compatible with code generated without that switch. +Use it to conform to a non-default application binary interface. + +@item -fshort-wchar +@opindex fshort-wchar +Override the underlying type for @samp{wchar_t} to be @samp{short +unsigned int} instead of the default for the target. This option is +useful for building programs to run under WINE@. + +@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate +code that is not binary compatible with code generated without that switch. +Use it to conform to a non-default application binary interface. + @item -fshared-data @opindex fshared-data Requests that the data and non-@code{const} variables of this @@ -9888,9 +9911,12 @@ three-way choice. @item -fpack-struct @opindex fpack-struct -Pack all structure members together without holes. Usually you would -not want to use this option, since it makes the code suboptimal, and -the offsets of structure members won't agree with system libraries. +Pack all structure members together without holes. + +@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate +code that is not binary compatible with code generated without that switch. +Additionally, it makes the code suboptimial. +Use it to conform to a non-default application binary interface. @item -finstrument-functions @opindex finstrument-functions @@ -9987,8 +10013,10 @@ This option and its counterpart, @option{-fno-leading-underscore}, forcibly change the way C symbols are represented in the object file. One use is to help link with legacy assembly code. -Be warned that you should know what you are doing when invoking this -option, and that not all targets provide complete support for it. +@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to +generate code that is not binary compatible with code generated without that +switch. Use it to conform to a non-default application binary interface. +Not all targets provide complete support for this switch. @end table @c man end diff --git a/contrib/gcc/doc/makefile.texi b/contrib/gcc/doc/makefile.texi index 69d621b..6d6b025 100644 --- a/contrib/gcc/doc/makefile.texi +++ b/contrib/gcc/doc/makefile.texi @@ -48,9 +48,9 @@ You can specify specific tests by setting RUNTESTFLAGS to be the name of the @file{.exp} file, optionally followed by (for some tests) an equals and a file wildcard, like: -@example +@smallexample make check-gcc RUNTESTFLAGS="execute.exp=19980413-*" -@end example +@end smallexample Note that running the testsuite may require additional tools be installed, such as TCL or dejagnu. diff --git a/contrib/gcc/doc/rtl.texi b/contrib/gcc/doc/rtl.texi index 2151047..56a02d3 100644 --- a/contrib/gcc/doc/rtl.texi +++ b/contrib/gcc/doc/rtl.texi @@ -2316,11 +2316,11 @@ An hypothetical example might be a pattern for an addition that can either wrap around or use saturating addition depending on the value of a special control register: -@example +@smallexample (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3) (reg:SI 4)] 0)) (use (reg:SI 1))]) -@end example +@end smallexample @noindent @@ -2552,10 +2552,10 @@ where @var{z} is an index register and @var{i} is a constant. Here is an example of its use: -@example +@smallexample (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42) (reg:SI 48)))) -@end example +@end smallexample This says to modify pseudo register 42 by adding the contents of pseudo register 48 to it, after the use of what ever 42 points to. diff --git a/contrib/gcc/doc/standards.texi b/contrib/gcc/doc/standards.texi index 25fbb45..b3e8b18 100644 --- a/contrib/gcc/doc/standards.texi +++ b/contrib/gcc/doc/standards.texi @@ -168,11 +168,19 @@ information concerning the history of C that is available online, see There is no formal written standard for Objective-C@. The most authoritative manual is ``Object-Oriented Programming and the -Objective-C Language'', available at a number of web sites; -@uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} has a -recent version, while @uref{http://www.toodarkpark.org/computers/objc/} -is an older example. @uref{http://www.gnustep.org} includes useful -information as well. +Objective-C Language'', available at a number of web sites + +@itemize +@item +@uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} +is a recent version +@item +@uref{http://www.toodarkpark.org/computers/objc/} +is an older example +@item +@uref{http://www.gnustep.org} +has additional useful information +@end itemize @xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, GNAT Reference Manual}, for information on standard diff --git a/contrib/gcc/doc/tm.texi b/contrib/gcc/doc/tm.texi index 2e3ad05..d8821c5 100644 --- a/contrib/gcc/doc/tm.texi +++ b/contrib/gcc/doc/tm.texi @@ -156,11 +156,11 @@ such as one option that enables many options, some of which select multilibs. Example nonsensical definition, where @code{-malt-abi}, @code{-EB}, and @code{-mspoo} cause different multilibs to be chosen: -@example +@smallexample #define TARGET_OPTION_TRANSLATE_TABLE \ @{ "-fast", "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \ @{ "-compat", "-EB -malign=4 -mspoo" @} -@end example +@end smallexample @findex CPP_SPEC @item CPP_SPEC @@ -7423,6 +7423,11 @@ argument @var{name} is the name of an assembler symbol (for use with @item DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. +@findex DBX_OUTPUT_NFUN +@item DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl}) +Define this macro if the target machine requires special handling to +output an @code{N_FUN} entry for the function @var{decl}. + @findex DBX_OUTPUT_ENUM @item DBX_OUTPUT_ENUM (@var{stream}, @var{type}) Define this macro if the target machine requires special handling to diff --git a/contrib/gcc/doc/trouble.texi b/contrib/gcc/doc/trouble.texi index 09026fe..4cfef9f 100644 --- a/contrib/gcc/doc/trouble.texi +++ b/contrib/gcc/doc/trouble.texi @@ -105,11 +105,13 @@ libraries and debuggers on certain systems. @itemize @bullet @item -G++ does not do name mangling in the same way as other C++ -compilers. This means that object files compiled with one compiler -cannot be used with another. +On many platforms, GCC supports a different ABI for C++ than do other +compilers, so the object files compiled by GCC cannot be used with object +files generated by another C++ compiler. -This effect is intentional, to protect you from more subtle problems. +An area where the difference is most apparent is name mangling. The use +of different name mangling is intentional, to protect you from more subtle +problems. Compilers differ as to many internal details of C++ implementation, including: how class instances are laid out, how multiple inheritance is implemented, and how virtual function calls are handled. If the name |