diff options
author | kan <kan@FreeBSD.org> | 2004-07-28 03:11:36 +0000 |
---|---|---|
committer | kan <kan@FreeBSD.org> | 2004-07-28 03:11:36 +0000 |
commit | 5e00ec74d8ce58f99801200d4d3d0412c7cc1b28 (patch) | |
tree | 052f4bb635f2bea2c5e350bd60c902be100a0d1e /contrib/gcc/doc | |
parent | 87b8398a7d9f9bf0e28bbcd54a4fc27db2125f38 (diff) | |
download | FreeBSD-src-5e00ec74d8ce58f99801200d4d3d0412c7cc1b28.zip FreeBSD-src-5e00ec74d8ce58f99801200d4d3d0412c7cc1b28.tar.gz |
Gcc 3.4.2 20040728.
Diffstat (limited to 'contrib/gcc/doc')
34 files changed, 10235 insertions, 7656 deletions
diff --git a/contrib/gcc/doc/bugreport.texi b/contrib/gcc/doc/bugreport.texi index d9613ef..9e10af9 100644 --- a/contrib/gcc/doc/bugreport.texi +++ b/contrib/gcc/doc/bugreport.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001, 2003 Free Software Foundation, Inc. +@c 1999, 2000, 2001, 2003, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -76,8 +76,8 @@ compiler bug. @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 my idea of ``an extension'' or ``support -for traditional practice''. +``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 @@ -88,7 +88,7 @@ suggestions for improvement of GCC are welcome in any case. @section How and where to Report Bugs @cindex compiler bugs, reporting -Bugs should be reported to our bug database. Please refer to +Bugs should be reported to the GCC bug database. Please refer to @uref{http://gcc.gnu.org/bugs.html} for up-to-date instructions how to submit bug reports. Copies of this file in HTML (@file{bugs.html}) and plain text (@file{BUGS}) are also part of GCC releases. diff --git a/contrib/gcc/doc/c-tree.texi b/contrib/gcc/doc/c-tree.texi index fbc90fa3..d1afe65 100644 --- a/contrib/gcc/doc/c-tree.texi +++ b/contrib/gcc/doc/c-tree.texi @@ -1,4 +1,4 @@ -@c Copyright (c) 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. +@c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004 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. @@ -98,24 +98,24 @@ Many macros behave as predicates. Many, although not all, of these predicates end in @samp{_P}. Do not rely on the result type of these macros being of any particular type. You may, however, rely on the fact that the type can be compared to @code{0}, so that statements like -@example +@smallexample if (TEST_P (t) && !TEST_P (y)) x = 1; -@end example +@end smallexample @noindent and -@example +@smallexample int i = (TEST_P (t) != 0); -@end example +@end smallexample @noindent are legal. Macros that return @code{int} values now may be changed to return @code{tree} values, or other pointers in the future. Even those that continue to return @code{int} may return multiple nonzero codes where previously they returned only zero and one. Therefore, you should not write code like -@example +@smallexample if (TEST_P (t) == 1) -@end example +@end smallexample @noindent as this code is not guaranteed to work correctly in the future. @@ -124,7 +124,7 @@ functions described here. In particular, no guarantee is given that the values are lvalues. In general, the names of macros are all in uppercase, while the names of -functions are entirely in lower case. There are rare exceptions to this +functions are entirely in lowercase. There are rare exceptions to this rule. You should assume that any macro or function whose name is made up entirely of uppercase letters may evaluate its arguments more than once. You may assume that a macro or function whose name is made up @@ -555,11 +555,9 @@ This node is used to represent a type the knowledge of which is insufficient for a sound processing. @item OFFSET_TYPE -This node is used to represent a data member; for example a -pointer-to-data-member is represented by a @code{POINTER_TYPE} whose -@code{TREE_TYPE} is an @code{OFFSET_TYPE}. For a data member @code{X::m} -the @code{TYPE_OFFSET_BASETYPE} is @code{X} and the @code{TREE_TYPE} is -the type of @code{m}. +This node is used to represent a pointer-to-data member. For a data +member @code{X::m} the @code{TYPE_OFFSET_BASETYPE} is @code{X} and the +@code{TREE_TYPE} is the type of @code{m}. @item TYPENAME_TYPE Used to represent a construct of the form @code{typename T::A}. The @@ -790,7 +788,7 @@ This predicate holds whenever its argument represents a class-type with default constructor. @item CLASSTYPE_HAS_MUTABLE -@item TYPE_HAS_MUTABLE_P +@itemx TYPE_HAS_MUTABLE_P These predicates hold for a class-type having a mutable data member. @item CLASSTYPE_NON_POD_P @@ -873,15 +871,15 @@ This predicate holds if the declaration was implicitly generated by the compiler. For example, this predicate will hold of an implicitly declared member function, or of the @code{TYPE_DECL} implicitly generated for a class type. Recall that in C++ code like: -@example +@smallexample struct S @{@}; -@end example +@end smallexample @noindent is roughly equivalent to C code like: -@example +@smallexample struct S @{@}; typedef struct S S; -@end example +@end smallexample The implicitly generated @code{typedef} declaration is represented by a @code{TYPE_DECL} for which @code{DECL_ARTIFICIAL} holds. @@ -1021,34 +1019,35 @@ will always return the function itself, and @code{OVL_NEXT} will always be @code{NULL_TREE}. To determine the scope of a function, you can use the -@code{DECL_REAL_CONTEXT} macro. This macro will return the class +@code{DECL_CONTEXT} macro. This macro will return the class (either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a @code{NAMESPACE_DECL}) of which the function is a member. For a virtual function, this macro returns the class in which the function was actually defined, not the base class in which the virtual declaration -occurred. If a friend function is defined in a class scope, the -@code{DECL_CLASS_CONTEXT} macro can be used to determine the class in +occurred. + +If a friend function is defined in a class scope, the +@code{DECL_FRIEND_CONTEXT} macro can be used to determine the class in which it was defined. For example, in -@example +@smallexample class C @{ friend void f() @{@} @}; -@end example -the @code{DECL_REAL_CONTEXT} for @code{f} will be the -@code{global_namespace}, but the @code{DECL_CLASS_CONTEXT} will be the +@end smallexample +@noindent +the @code{DECL_CONTEXT} for @code{f} will be the +@code{global_namespace}, but the @code{DECL_FRIEND_CONTEXT} will be the @code{RECORD_TYPE} for @code{C}. -The @code{DECL_REAL_CONTEXT} and @code{DECL_CLASS_CONTEXT} are not -available in C; instead you should simply use @code{DECL_CONTEXT}. In C, -the @code{DECL_CONTEXT} for a function maybe another function. This -representation indicates that the GNU nested function extension is in -use. For details on the semantics of nested functions, see the GCC -Manual. The nested function can refer to local variables in its +In C, the @code{DECL_CONTEXT} for a function maybe another function. +This representation indicates that the GNU nested function extension +is in use. For details on the semantics of nested functions, see the +GCC Manual. The nested function can refer to local variables in its containing function. Such references are not explicitly marked in the tree structure; back ends must look at the @code{DECL_CONTEXT} for the referenced @code{VAR_DECL}. If the @code{DECL_CONTEXT} for the referenced @code{VAR_DECL} is not the same as the function currently -being processed, and neither @code{DECL_EXTERNAL} nor @code{DECL_STATIC} -hold, then the reference is to a local variable in a containing -function, and the back end must take appropriate action. +being processed, and neither @code{DECL_EXTERNAL} nor +@code{DECL_STATIC} hold, then the reference is to a local variable in +a containing function, and the back end must take appropriate action. @menu * Function Basics:: Function names, linkage, and so forth. @@ -1379,7 +1378,7 @@ the expression has been omitted. A substatement may in fact be a list of statements, connected via their @code{TREE_CHAIN}s. So, you should always process the statement tree by looping over substatements, like this: -@example +@smallexample void process_stmt (stmt) tree stmt; @{ @@ -1398,7 +1397,7 @@ void process_stmt (stmt) stmt = TREE_CHAIN (stmt); @} @} -@end example +@end smallexample In other words, while the @code{then} clause of an @code{if} statement in C++ can be only one statement (although that one statement may be a compound statement), the intermediate representation will sometimes use @@ -1409,18 +1408,18 @@ several statements chained together. Used to represent an inline assembly statement. For an inline assembly statement like: -@example +@smallexample asm ("mov x, y"); -@end example +@end smallexample The @code{ASM_STRING} macro will return a @code{STRING_CST} node for @code{"mov x, y"}. If the original statement made use of the extended-assembly syntax, then @code{ASM_OUTPUTS}, @code{ASM_INPUTS}, and @code{ASM_CLOBBERS} will be the outputs, inputs, and clobbers for the statement, represented as @code{STRING_CST} nodes. The extended-assembly syntax looks like: -@example +@smallexample asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); -@end example +@end smallexample The first string is the @code{ASM_STRING}, containing the instruction template. The next two strings are the output and inputs, respectively; this statement has no clobbers. As this example indicates, ``plain'' @@ -1452,9 +1451,9 @@ the same type as the condition expression in the switch statement. Otherwise, if both @code{CASE_LOW} and @code{CASE_HIGH} are defined, the statement is a range of case labels. Such statements originate with the extension that allows users to write things of the form: -@example +@smallexample case 2 ... 5: -@end example +@end smallexample The first value will be @code{CASE_LOW}, while the second will be @code{CASE_HIGH}. @@ -1547,10 +1546,10 @@ This is used for branch prediction. Used to represent a C++ @code{catch} block. The @code{HANDLER_TYPE} is the type of exception that will be caught by this handler; it is -equal (by pointer equality) to @code{CATCH_ALL_TYPE} if this handler -is for all types. @code{HANDLER_PARMS} is the @code{DECL_STMT} for -the catch parameter, and @code{HANDLER_BODY} is the -@code{COMPOUND_STMT} for the block itself. +equal (by pointer equality) to @code{NULL} if this handler is for all +types. @code{HANDLER_PARMS} is the @code{DECL_STMT} for the catch +parameter, and @code{HANDLER_BODY} is the @code{COMPOUND_STMT} for the +block itself. @item IF_STMT @@ -1563,9 +1562,9 @@ evaluated, the statement should be executed. Then, the @code{TREE_VALUE} should be used as the conditional expression itself. This representation is used to handle C++ code like this: -@example +@smallexample if (int i = 7) @dots{} -@end example +@end smallexample where there is a new local variable (or variables) declared within the condition. @@ -1585,9 +1584,9 @@ the @code{LABEL_DECL} with @code{DECL_NAME}. If the function uses the G++ ``named return value'' extension, meaning that the function has been defined like: -@example +@smallexample S f(int) return s @{@dots{}@} -@end example +@end smallexample then there will be a @code{RETURN_INIT}. There is never a named returned value for a constructor. The first argument to the @code{RETURN_INIT} is the name of the object returned; the second @@ -1602,9 +1601,9 @@ constructed in the place where the object will be returned. Used to represent a @code{return} statement. The @code{RETURN_EXPR} is the expression returned; it will be @code{NULL_TREE} if the statement was just -@example +@smallexample return; -@end example +@end smallexample @item SCOPE_STMT @@ -1721,6 +1720,7 @@ This macro returns the attributes on the type @var{type}. @findex PTRMEM_CST_MEMBER @tindex VAR_DECL @tindex NEGATE_EXPR +@tindex ABS_EXPR @tindex BIT_NOT_EXPR @tindex TRUTH_NOT_EXPR @tindex ADDR_EXPR @@ -1803,9 +1803,9 @@ noted otherwise, the operands to an expression are accessed using the @code{TREE_OPERAND} macro. For example, to access the first operand to a binary plus expression @code{expr}, use: -@example +@smallexample TREE_OPERAND (expr, 0) -@end example +@end smallexample @noindent As this example indicates, the operands are zero-indexed. @@ -1819,10 +1819,11 @@ These nodes represent integer constants. Note that the type of these constants is obtained with @code{TREE_TYPE}; they are not always of type @code{int}. In particular, @code{char} constants are represented with @code{INTEGER_CST} nodes. The value of the integer constant @code{e} is -given by @example +given by +@smallexample ((TREE_INT_CST_HIGH (e) << HOST_BITS_PER_WIDE_INT) + TREE_INST_CST_LOW (e)) -@end example +@end smallexample @noindent HOST_BITS_PER_WIDE_INT is at least thirty-two on all platforms. Both @code{TREE_INT_CST_HIGH} and @code{TREE_INT_CST_LOW} return a @@ -1893,11 +1894,11 @@ or @code{UNION_TYPE} within which the pointer points), and the Note that the @code{DECL_CONTEXT} for the @code{PTRMEM_CST_MEMBER} is in general different from the @code{PTRMEM_CST_CLASS}. For example, given: -@example +@smallexample struct B @{ int i; @}; struct D : public B @{@}; int D::*dp = &D::i; -@end example +@end smallexample @noindent The @code{PTRMEM_CST_CLASS} for @code{&D::i} is @code{D}, even though the @code{DECL_CONTEXT} for the @code{PTRMEM_CST_MEMBER} is @code{B}, @@ -1913,6 +1914,23 @@ These nodes represent unary negation of the single operand, for both integer and floating-point types. The type of negation can be determined by looking at the type of the expression. +The behavior of this operation on signed arithmetic overflow is +controlled by the @code{flag_wrapv} and @code{flag_trapv} variables. + +@item ABS_EXPR +These nodes represent the absolute value of the single operand, for +both integer and floating-point types. This is typically used to +implement the @code{abs}, @code{labs} and @code{llabs} builtins for +integer types, and the @code{fabs}, @code{fabsf} and @code{fabsl} +builtins for floating point types. The type of abs operation can +be determined by looking at the type of the expression. + +This node is not used for complex types. To represent the modulus +or complex abs of a complex value, use the @code{BUILT_IN_CABS}, +@code{BUILT_IN_CABSF} or @code{BUILT_IN_CABSL} builtins, as used +to implement the C99 @code{cabs}, @code{cabsf} and @code{cabsl} +built-in functions. + @item BIT_NOT_EXPR These nodes represent bitwise complement, and will always have integral type. The only operand is the value to be complemented. @@ -1974,7 +1992,7 @@ real part and the second operand is the imaginary part. These nodes represent the conjugate of their operand. @item REALPART_EXPR -@item IMAGPART_EXPR +@itemx IMAGPART_EXPR These nodes represent respectively the real and the imaginary parts of complex numbers (their sole argument). @@ -2066,6 +2084,9 @@ The @code{TRUNC_MOD_EXPR} of two operands @code{a} and @code{b} is always @code{a - (a/b)*b} where the division is as if computed by a @code{TRUNC_DIV_EXPR}. +The behavior of these operations on signed arithmetic overflow is +controlled by the @code{flag_wrapv} and @code{flag_trapv} variables. + @item ARRAY_REF These nodes represent array accesses. The first operand is the array; the second is the index. To calculate the address of the memory @@ -2161,9 +2182,9 @@ sites. @item STMT_EXPR These nodes are used to represent GCC's statement-expression extension. The statement-expression extension allows code like this: -@example +@smallexample int f() @{ return (@{ int j; j = 3; j + 7; @}); @} -@end example +@end smallexample In other words, an sequence of statements may occur where a single expression would normally appear. The @code{STMT_EXPR} node represents such an expression. The @code{STMT_EXPR_STMT} gives the statement @@ -2172,13 +2193,13 @@ value of the expression is the value of the last sub-statement in the @code{COMPOUND_STMT}. More precisely, the value is the value computed by the last @code{EXPR_STMT} in the outermost scope of the @code{COMPOUND_STMT}. For example, in: -@example +@smallexample (@{ 3; @}) -@end example +@end smallexample the value is @code{3} while in: -@example +@smallexample (@{ if (x) @{ 3; @} @}) -@end example +@end smallexample (represented by a nested @code{COMPOUND_STMT}), there is no value. If the @code{STMT_EXPR} does not yield a value, it's type will be @code{void}. @@ -2214,10 +2235,7 @@ second operand is a @code{TREE_LIST}. If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is a @code{RECORD_TYPE} or @code{UNION_TYPE}, then the @code{TREE_PURPOSE} of each node in the @code{TREE_LIST} will be a @code{FIELD_DECL} and the @code{TREE_VALUE} of each node will be the -expression used to initialize that field. You should not depend on the -fields appearing in any particular order, nor should you assume that all -fields will be represented. Unrepresented fields may be assigned any -value. +expression used to initialize that field. If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is an @code{ARRAY_TYPE}, then the @code{TREE_PURPOSE} of each element in the @@ -2227,8 +2245,10 @@ again, the @code{TREE_VALUE} is the corresponding initializer. If the @code{TREE_PURPOSE} is @code{NULL_TREE}, then the initializer is for the next available array element. -Conceptually, before any initialization is done, the entire area of -storage is initialized to zero. +In the front end, you should not depend on the fields appearing in any +particular order. However, in the middle end, fields must appear in +declaration order. You should not assume that all fields will be +represented. Unrepresented fields will be set to zero. @item COMPOUND_LITERAL_EXPR @findex COMPOUND_LITERAL_EXPR_DECL_STMT diff --git a/contrib/gcc/doc/compat.texi b/contrib/gcc/doc/compat.texi index 274368a..5b02ebc 100644 --- a/contrib/gcc/doc/compat.texi +++ b/contrib/gcc/doc/compat.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 2002 Free Software Foundation, Inc. +@c Copyright (C) 2002, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -133,9 +133,9 @@ 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 -@example +@smallexample -I@var{gcc_install_directory}/include/c++/3.3 -@end example +@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 diff --git a/contrib/gcc/doc/configfiles.texi b/contrib/gcc/doc/configfiles.texi index c6c60bb..f24b85d 100644 --- a/contrib/gcc/doc/configfiles.texi +++ b/contrib/gcc/doc/configfiles.texi @@ -50,7 +50,7 @@ the files listed in @code{outputs} there are also generated. The following configuration headers are created from the Makefile, using @file{mkconfig.sh}, rather than directly by @file{configure}. -@file{config.h}, @file{hconfig.h} and @file{tconfig.h} all contain the +@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, @@ -63,7 +63,7 @@ these include the autoconfigured headers generated by @item @file{config.h}, for use in programs that run on the host machine. @item -@file{hconfig.h}, for use in programs that run on the build machine. +@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. diff --git a/contrib/gcc/doc/configterms.texi b/contrib/gcc/doc/configterms.texi index 39b3152..f97de5b 100644 --- a/contrib/gcc/doc/configterms.texi +++ b/contrib/gcc/doc/configterms.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 2001, 2002 Free Software Foundation, Inc. +@c Copyright (C) 2001, 2002, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -34,8 +34,8 @@ 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 -(although I propose calling it a @dfn{crossback}). +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 diff --git a/contrib/gcc/doc/contrib.texi b/contrib/gcc/doc/contrib.texi index 3eb3b22..8c24193 100644 --- a/contrib/gcc/doc/contrib.texi +++ b/contrib/gcc/doc/contrib.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000, -@c 2001,2002,2003 Free Software Foundation, Inc. +@c 2001,2002,2003,2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -29,12 +29,20 @@ James van Artsdalen wrote the code that makes efficient use of the Intel 80387 register stack. @item +Abramo and Roberto Bagnara for the SysV68 Motorola 3300 Delta Series +port. + +@item Alasdair Baird for various bug fixes. @item Giovanni Bajo for analyzing lots of complicated C++ problem reports. @item +Peter Barada for his work to improve code generation for new +ColdFire cores. + +@item Gerald Baumgartner added the signature extension to the C++ front end. @item @@ -47,11 +55,11 @@ Scott Bambrough for help porting the Java compiler. Wolfgang Bangerth for processing tons of bug reports. @item -Jon Beniston for his Windows port of Java. +Jon Beniston for his Microsoft Windows port of Java. @item Daniel Berlin for better DWARF2 support, faster/better optimizations, -improved alias analysis, plus migrating us to Bugzilla. +improved alias analysis, plus migrating GCC to Bugzilla. @item Geoff Berry for his Java object serialization work and various patches. @@ -76,7 +84,7 @@ Eric Botcazou for fixing middle- and backend bugs left and right. @item Per Bothner for his direction via the steering committee and various -improvements to our infrastructure for supporting new languages. Chill +improvements to the infrastructure for supporting new languages. Chill front end implementation. Initial implementations of cpplib, fix-header, config.guess, libio, and past C++ library (libg++) maintainer. Dreaming up, designing and implementing much of GCJ. @@ -113,8 +121,8 @@ Stephan Buys for contributing Doxygen notes for libstdc++. @item Paolo Carlini for libstdc++ work: lots of efficiency improvements to -the string class, hard detective work on the frustrating localization -issues, and keeping up with the problem reports. +the C++ strings, streambufs and formatted I/O, hard detective work on +the frustrating localization issues, and keeping up with the problem reports. @item John Carr for his alias work, SPARC hacking, infrastructure improvements, @@ -143,7 +151,7 @@ Eric Christopher for his Java porting help and clean-ups. Branko Cibej for more warning contributions. @item -The @uref{http://www.classpath.org,,GNU Classpath project} +The @uref{http://www.gnu.org/software/classpath/,,GNU Classpath project} for all of their merged runtime code. @item @@ -154,6 +162,10 @@ other random hacking. Michael Cook for libstdc++ cleanup patches to reduce warnings. @item +R. Kelley Cook for making GCC buildable from a read-only directory as +well as other miscellaneous build process and documentation clean-ups. + +@item Ralf Corsepius for SH testing and minor bugfixing. @item @@ -167,6 +179,10 @@ Alex Crain provided changes for the 3b1. Ian Dall for major improvements to the NS32k port. @item +Paul Dale for his work to add uClinux platform support to the +m68k backend. + +@item Dario Dariol contributed the four varieties of sample programs that print a copy of their source. @@ -181,7 +197,7 @@ DJ Delorie for the DJGPP port, build and libiberty maintenance, and various bug fixes. @item -Gabriel Dos Reis for contributions to g++, contributions and +Gabriel Dos Reis for contributions to G++, contributions and maintenance of GCC diagnostics infrastructure, libstdc++-v3, including valarray<>, complex<>, maintaining the numerics library (including that pesky <limits> :-) and keeping up-to-date anything @@ -273,7 +289,7 @@ via the steering committee. Anthony Green for his @option{-Os} contributions and Java front end work. @item -Stu Grossman for gdb hacking, allowing GCJ developers to debug our code. +Stu Grossman for gdb hacking, allowing GCJ developers to debug Java code. @item Michael K. Gschwind contributed the port to the PDP-11. @@ -303,7 +319,7 @@ fixes. Dara Hazeghi for wading through myriads of target-specific bug reports. @item -Kate Hedstrom for staking the g77 folks with an initial testsuite. +Kate Hedstrom for staking the G77 folks with an initial testsuite. @item Richard Henderson for his ongoing SPARC, alpha, ia32, and ia64 work, loop @@ -324,7 +340,7 @@ Kazu Hirata for caring and feeding the Renesas H8/300 port and various fixes. @item Manfred Hollstein for his ongoing work to keep the m88k alive, lots -of testing and bug fixing, particularly of our configury code. +of testing and bug fixing, particularly of GCC configury code. @item Steve Holmgren for MachTen patches. @@ -336,6 +352,10 @@ Jan Hubicka for his x86 port improvements. Falk Hueffner for working on C and optimization bug reports. @item +Bernardo Innocenti for his m68k work, including merging of +ColdFire improvements and uClinux support. + +@item Christian Iseli for various bug fixes. @item @@ -381,7 +401,7 @@ Geoffrey Keating for his ongoing work to make the PPC work for GNU/Linux and his automatic regression tester. @item -Brendan Kehoe for his ongoing work with g++ and for a lot of early work +Brendan Kehoe for his ongoing work with G++ and for a lot of early work in just about every part of libstdc++. @item @@ -401,7 +421,7 @@ head maintainer of GCC for several years. @item Mumit Khan for various contributions to the Cygwin and Mingw32 ports and -maintaining binary releases for Windows hosts, and for massive libstdc++ +maintaining binary releases for Microsoft Windows hosts, and for massive libstdc++ porting work to Cygwin/Mingw32. @item @@ -417,7 +437,7 @@ Thomas Koenig for various bug fixes. Bruce Korb for the new and improved fixincludes code. @item -Benjamin Kosnik for his g++ work and for leading the libstdc++-v3 effort. +Benjamin Kosnik for his G++ work and for leading the libstdc++-v3 effort. @item Charles LaBrec contributed the support for the Integrated Solutions @@ -499,7 +519,7 @@ for Java test code. Bryce McKinlay for numerous GCJ and libgcj fixes and improvements. @item -Adam Megacz for his work on the Windows port of GCJ. +Adam Megacz for his work on the Microsoft Windows port of GCJ. @item Michael Meissner for LRS framework, ia32, m32r, v850, m88k, MIPS, @@ -507,7 +527,7 @@ powerpc, haifa, ECOFF debug support, and other assorted hacking. @item Jason Merrill for his direction via the steering committee and leading -the g++ effort. +the G++ effort. @item David Miller for his direction via the steering committee, lots of @@ -548,7 +568,8 @@ Linux kernels. Mike Moreton for his various Java patches. @item -David Mosberger-Tang for various Alpha improvements. +David Mosberger-Tang for various Alpha improvements, and for the initial +IA-64 port. @item Stephen Moshier contributed the floating point emulator that assists in @@ -606,7 +627,7 @@ amazing testing work, including keeping libtool issues sane and happy. Melissa O'Neill for various NeXT fixes. @item -Rainer Orth for random MIPS work, including improvements to our o32 +Rainer Orth for random MIPS work, including improvements to GCC's o32 ABI support, improvements to dejagnu's MIPS support, Java configuration clean-ups and porting work, etc. @@ -636,6 +657,9 @@ Ovidiu Predescu for his work on the Objective-C front end and runtime libraries. @item +Jerry Quinn for major performance improvements in C++ formatted I/O. + +@item Ken Raeburn for various improvements to checker, MIPS ports and various cleanups in the compiler. @@ -666,12 +690,16 @@ Craig Rodrigues for processing tons of bug reports. Gavin Romig-Koch for lots of behind the scenes MIPS work. @item -Ken Rose for fixes to our delay slot filling code. +Ken Rose for fixes to GCC's delay slot filling code. @item Paul Rubin wrote most of the preprocessor. @item +P@'etur Run@'olfsson for major performance improvements in C++ formatted I/O and +large file support in C++ filebuf. + +@item Chip Salzenberg for libstdc++ patches and improvements to locales, traits, Makefiles, libio, libtool hackery, and ``long long'' support. @@ -724,11 +752,11 @@ folding and help with the original VAX & m68k ports. @item Kenny Simpson for prompting libstdc++ fixes due to defect reports from -the LWG (thereby keeping us in line with updates from the ISO). +the LWG (thereby keeping GCC in line with updates from the ISO). @item Franz Sirl for his ongoing work with making the PPC port stable -for linux. +for GNU/Linux. @item Andrey Slepuhin for assorted AIX hacking. @@ -750,7 +778,7 @@ testsuite entries. Brad Spencer for contributions to the GLIBCPP_FORCE_NEW technique. @item -Richard Stallman, for writing the original gcc and launching the GNU project. +Richard Stallman, for writing the original GCC and launching the GNU project. @item Jan Stein of the Chalmers Computer Society provided support for @@ -769,7 +797,7 @@ Graham Stott for various infrastructure improvements. John Stracke for his Java HTTP protocol fixes. @item -Mike Stump for his Elxsi port, g++ contributions over the years and more +Mike Stump for his Elxsi port, G++ contributions over the years and more recently his vxworks contributions @item diff --git a/contrib/gcc/doc/contribute.texi b/contrib/gcc/doc/contribute.texi index 0aec268..a90c048 100644 --- a/contrib/gcc/doc/contribute.texi +++ b/contrib/gcc/doc/contribute.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001 Free Software Foundation, Inc. +@c 1999, 2000, 2001, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -7,7 +7,7 @@ @chapter Contributing to GCC Development If you would like to help pretest GCC releases to assure they work well, -our current development sources are available by CVS (see +current development sources are available by CVS (see @uref{http://gcc.gnu.org/cvs.html}). Source and binary snapshots are also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}. diff --git a/contrib/gcc/doc/cpp.texi b/contrib/gcc/doc/cpp.texi index 070e31c..3697887 100644 --- a/contrib/gcc/doc/cpp.texi +++ b/contrib/gcc/doc/cpp.texi @@ -9,7 +9,7 @@ @copying @c man begin COPYRIGHT Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998, 1999, 2000, 2001, 2002, 2003 +1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document @@ -104,6 +104,7 @@ useful on its own. Overview +* Character sets:: * Initial processing:: * Tokenization:: * The preprocessing language:: @@ -233,11 +234,62 @@ manual refer to GNU CPP. @c man end @menu +* Character sets:: * Initial processing:: * Tokenization:: * The preprocessing language:: @end menu +@node Character sets +@section Character sets + +Source code character set processing in C and related languages is +rather complicated. The C standard discusses two character sets, but +there are really at least four. + +The files input to CPP might be in any character set at all. CPP's +very first action, before it even looks for line boundaries, is to +convert the file into the character set it uses for internal +processing. That set is what the C standard calls the @dfn{source} +character set. It must be isomorphic with ISO 10646, also known as +Unicode. CPP uses the UTF-8 encoding of Unicode. + +At present, GNU CPP does not implement conversion from arbitrary file +encodings to the source character set. Use of any encoding other than +plain ASCII or UTF-8, except in comments, will cause errors. Use of +encodings that are not strict supersets of ASCII, such as Shift JIS, +may cause errors even if non-ASCII characters appear only in comments. +We plan to fix this in the near future. + +All preprocessing work (the subject of the rest of this manual) is +carried out in the source character set. If you request textual +output from the preprocessor with the @option{-E} option, it will be +in UTF-8. + +After preprocessing is complete, string and character constants are +converted again, into the @dfn{execution} character set. This +character set is under control of the user; the default is UTF-8, +matching the source character set. Wide string and character +constants have their own character set, which is not called out +specifically in the standard. Again, it is under control of the user. +The default is UTF-16 or UTF-32, whichever fits in the target's +@code{wchar_t} type, in the target machine's byte +order.@footnote{UTF-16 does not meet the requirements of the C +standard for a wide character set, but the choice of 16-bit +@code{wchar_t} is enshrined in some system ABIs so we cannot fix +this.} Octal and hexadecimal escape sequences do not undergo +conversion; @t{'\x12'} has the value 0x12 regardless of the currently +selected execution character set. All other escapes are replaced by +the character in the source character set that they represent, then +converted to the execution character set, just like unescaped +characters. + +GCC does not permit the use of characters outside the ASCII range, nor +@samp{\u} and @samp{\U} escapes, in identifiers. We hope this will +change eventually, but there are problems with the standard semantics +of such ``extended identifiers'' which must be resolved through the +ISO C and C++ committees first. + @node Initial processing @section Initial processing @@ -251,28 +303,19 @@ standard. @enumerate @item -@cindex character sets @cindex line endings The input file is read into memory and broken into lines. -CPP expects its input to be a text file, that is, an unstructured -stream of ASCII characters, with some characters indicating the end of a -line of text. Extended ASCII character sets, such as ISO Latin-1 or -Unicode encoded in UTF-8, are also acceptable. Character sets that are -not strict supersets of seven-bit ASCII will not work. We plan to add -complete support for international character sets in a future release. - Different systems use different conventions to indicate the end of a line. GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR -LF}}, @kbd{CR}, and @kbd{@w{LF CR}} as end-of-line markers. The first -three are the canonical sequences used by Unix, DOS and VMS, and the -classic Mac OS (before OSX) respectively. You may therefore safely copy -source code written on any of those systems to a different one and use -it without conversion. (GCC may lose track of the current line number -if a file doesn't consistently use one convention, as sometimes happens -when it is edited on computers with different conventions that share a -network file system.) @kbd{@w{LF CR}} is included because it has been -reported as an end-of-line marker under exotic conditions. +LF}} and @kbd{CR} as end-of-line markers. These are the canonical +sequences used by Unix, DOS and VMS, and the classic Mac OS (before +OSX) respectively. You may therefore safely copy source code written +on any of those systems to a different one and use it without +conversion. (GCC may lose track of the current line number if a file +doesn't consistently use one convention, as sometimes happens when it +is edited on computers with different conventions that share a network +file system.) If the last line of any input file lacks an end-of-line marker, the end of the file is considered to implicitly supply one. The C standard says @@ -293,23 +336,25 @@ obsolete systems that lack some of C's punctuation to use C@. For example, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character constant for a newline. -Trigraphs are not popular and many compilers implement them incorrectly. -Portable code should not rely on trigraphs being either converted or -ignored. If you use the @option{-Wall} or @option{-Wtrigraphs} options, -GCC will warn you when a trigraph would change the meaning of your -program if it were converted. +Trigraphs are not popular and many compilers implement them +incorrectly. Portable code should not rely on trigraphs being either +converted or ignored. With @option{-Wtrigraphs} GCC will warn you +when a trigraph may change the meaning of your program if it were +converted. @xref{Wtrigraphs}. -In a string constant, you can prevent a sequence of question marks from -being confused with a trigraph by inserting a backslash between the -question marks. @t{"(??\?)"} is the string @samp{(???)}, not -@samp{(?]}. Traditional C compilers do not recognize this idiom. +In a string constant, you can prevent a sequence of question marks +from being confused with a trigraph by inserting a backslash between +the question marks, or by separating the string literal at the +trigraph and making use of string literal concatenation. @t{"(??\?)"} +is the string @samp{(???)}, not @samp{(?]}. Traditional C compilers +do not recognize these idioms. The nine trigraphs and their replacements are -@example +@smallexample Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- Replacement: [ ] @{ @} # \ ^ | ~ -@end example +@end smallexample @item @cindex continued lines @@ -340,23 +385,23 @@ There are two kinds of comments. @dfn{Block comments} begin with @samp{/*} and continue until the next @samp{*/}. Block comments do not nest: -@example +@smallexample /* @r{this is} /* @r{one comment} */ @r{text outside comment} -@end example +@end smallexample @dfn{Line comments} begin with @samp{//} and continue to the end of the current line. Line comments do not nest either, but it does not matter, because they would end in the same place anyway. -@example +@smallexample // @r{this is} // @r{one comment} @r{text outside comment} -@end example +@end smallexample @end enumerate It is safe to put line comments inside block comments, or vice versa. -@example +@smallexample @group /* @r{block comment} // @r{contains line comment} @@ -365,19 +410,19 @@ It is safe to put line comments inside block comments, or vice versa. // @r{line comment} /* @r{contains block comment} */ @end group -@end example +@end smallexample But beware of commenting out one end of a block comment with a line comment. -@example +@smallexample @group // @r{l.c.} /* @r{block comment begins} @r{oops! this isn't a comment anymore} */ @end group -@end example +@end smallexample -Comments are not recognized within string literals. +Comments are not recognized within string literals. @t{@w{"/* blah */"}} is the string constant @samp{@w{/* blah */}}, not an empty string. @@ -392,7 +437,7 @@ next line with backslash-newline. You can even split @samp{/*}, @samp{*/}, and @samp{//} onto multiple lines with backslash-newline. For example: -@example +@smallexample @group /\ * @@ -402,7 +447,7 @@ ne FO\ O 10\ 20 @end group -@end example +@end smallexample @noindent is equivalent to @code{@w{#define FOO 1020}}. All these tricks are @@ -437,7 +482,7 @@ Once the input file is broken into tokens, the token boundaries never change, except when the @samp{##} preprocessing operator is used to paste tokens together. @xref{Concatenation}. For example, -@example +@smallexample @group #define foo() bar foo()baz @@ -445,7 +490,7 @@ foo()baz @emph{not} @expansion{} barbaz @end group -@end example +@end smallexample The compiler does not re-tokenize the preprocessor's output. Each preprocessing token becomes one compiler token. @@ -545,10 +590,10 @@ punctuation in obsolete systems. It has no negative side effects, unlike trigraphs, but does not cover as much ground. The digraphs and their corresponding normal punctuators are: -@example +@smallexample Digraph: <% %> <: :> %: %:%: Punctuator: @{ @} [ ] # ## -@end example +@end smallexample @cindex other tokens Any other single character is considered ``other.'' It is passed on to @@ -568,10 +613,10 @@ silently ignored, just as any other character would be. In running text, NUL is considered white space. For example, these two directives have the same meaning. -@example +@smallexample #define X^@@1 #define X 1 -@end example +@end smallexample @noindent (where @samp{^@@} is ASCII NUL)@. Within string or character constants, @@ -746,15 +791,15 @@ file, followed by the output that comes from the text after the @samp{#include} directive. For example, if you have a header file @file{header.h} as follows, -@example +@smallexample char *test (void); -@end example +@end smallexample @noindent and a main program called @file{program.c} that uses the header file, like this, -@example +@smallexample int x; #include "header.h" @@ -763,13 +808,13 @@ main (void) @{ puts (test ()); @} -@end example +@end smallexample @noindent the compiler will see the same token stream as it would if @file{program.c} read -@example +@smallexample int x; char *test (void); @@ -778,7 +823,7 @@ main (void) @{ puts (test ()); @} -@end example +@end smallexample Included files are not limited to declarations and macro definitions; those are merely the typical uses. Any fragment of a C program can be @@ -805,12 +850,12 @@ GCC looks in several different places for headers. On a normal Unix system, if you do not instruct it otherwise, it will look for headers requested with @code{@w{#include <@var{file}>}} in: -@example +@smallexample /usr/local/include -/usr/lib/gcc-lib/@var{target}/@var{version}/include +@var{libdir}/gcc/@var{target}/@var{version}/include /usr/@var{target}/include /usr/include -@end example +@end smallexample For C++ programs, it will also look in @file{/usr/include/g++-v3}, first. In the above, @var{target} is the canonical name of the system @@ -881,7 +926,7 @@ it will certainly waste time. The standard way to prevent this is to enclose the entire real contents of the file in a conditional, like this: -@example +@smallexample @group /* File foo. */ #ifndef FILE_FOO_SEEN @@ -891,7 +936,7 @@ of the file in a conditional, like this: #endif /* !FILE_FOO_SEEN */ @end group -@end example +@end smallexample This construct is commonly known as a @dfn{wrapper #ifndef}. When the header is included again, the conditional will be false, @@ -926,7 +971,7 @@ files to be included into your program. They might specify configuration parameters to be used on different sorts of operating systems, for instance. You could do this with a series of conditionals, -@example +@smallexample #if SYSTEM_1 # include "system_1.h" #elif SYSTEM_2 @@ -934,18 +979,18 @@ systems, for instance. You could do this with a series of conditionals, #elif SYSTEM_3 @dots{} #endif -@end example +@end smallexample That rapidly becomes tedious. Instead, the preprocessor offers the ability to use a macro for the header name. This is called a @dfn{computed include}. Instead of writing a header name as the direct argument of @samp{#include}, you simply put a macro name there instead: -@example +@smallexample #define SYSTEM_H "system_1.h" @dots{} #include SYSTEM_H -@end example +@end smallexample @noindent @code{SYSTEM_H} will be expanded, and the preprocessor will look for @@ -970,10 +1015,10 @@ string constant are the file to be included. CPP does not re-examine the string for embedded quotes, but neither does it process backslash escapes in the string. Therefore -@example +@smallexample #define HEADER "a\"b" #include HEADER -@end example +@end smallexample @noindent looks for a file named @file{a\"b}. CPP searches for the file according @@ -1018,9 +1063,9 @@ header is not protected from multiple inclusion (@pxref{Once-Only Headers}), it will recurse infinitely and cause a fatal error. You could include the old header with an absolute pathname: -@example +@smallexample #include "/usr/include/old-header.h" -@end example +@end smallexample @noindent This works, but is not clean; should the system headers ever move, you would have to edit the new headers to match. @@ -1139,29 +1184,29 @@ followed by the name of the macro and then the token sequence it should be an abbreviation for, which is variously referred to as the macro's @dfn{body}, @dfn{expansion} or @dfn{replacement list}. For example, -@example +@smallexample #define BUFFER_SIZE 1024 -@end example +@end smallexample @noindent defines a macro named @code{BUFFER_SIZE} as an abbreviation for the token @code{1024}. If somewhere after this @samp{#define} directive there comes a C statement of the form -@example +@smallexample foo = (char *) malloc (BUFFER_SIZE); -@end example +@end smallexample @noindent then the C preprocessor will recognize and @dfn{expand} the macro @code{BUFFER_SIZE}. The C compiler will see the same tokens as it would if you had written -@example +@smallexample foo = (char *) malloc (1024); -@end example +@end smallexample -By convention, macro names are written in upper case. Programs are +By convention, macro names are written in uppercase. Programs are easier to read when it is possible to tell at a glance which names are macros. @@ -1170,13 +1215,13 @@ continue the definition onto multiple lines, if necessary, using backslash-newline. When the macro is expanded, however, it will all come out on one line. For example, -@example +@smallexample #define NUMBERS 1, \ 2, \ 3 int x[] = @{ NUMBERS @}; @expansion{} int x[] = @{ 1, 2, 3 @}; -@end example +@end smallexample @noindent The most common visible consequence of this is surprising line numbers @@ -1191,25 +1236,25 @@ The C preprocessor scans your program sequentially. Macro definitions take effect at the place you write them. Therefore, the following input to the C preprocessor -@example +@smallexample foo = X; #define X 4 bar = X; -@end example +@end smallexample @noindent produces -@example +@smallexample foo = X; bar = 4; -@end example +@end smallexample When the preprocessor expands a macro name, the macro's expansion replaces the macro invocation, then the expansion is examined for more macros to expand. For example, -@example +@smallexample @group #define TABLESIZE BUFSIZE #define BUFSIZE 1024 @@ -1217,7 +1262,7 @@ TABLESIZE @expansion{} BUFSIZE @expansion{} 1024 @end group -@end example +@end smallexample @noindent @code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that @@ -1235,12 +1280,12 @@ at some point in the source file. @code{TABLESIZE}, defined as shown, will always expand using the definition of @code{BUFSIZE} that is currently in effect: -@example +@smallexample #define BUFSIZE 1020 #define TABLESIZE BUFSIZE #undef BUFSIZE #define BUFSIZE 37 -@end example +@end smallexample @noindent Now @code{TABLESIZE} expands (in two stages) to @code{37}. @@ -1259,24 +1304,24 @@ are called @dfn{function-like macros}. To define a function-like macro, you use the same @samp{#define} directive, but you put a pair of parentheses immediately after the macro name. For example, -@example +@smallexample #define lang_init() c_init() lang_init() @expansion{} c_init() -@end example +@end smallexample A function-like macro is only expanded if its name appears with a pair of parentheses after it. If you write just the name, it is left alone. This can be useful when you have a function and a macro of the same name, and you wish to use the function sometimes. -@example +@smallexample extern void foo(void); #define foo() /* optimized inline version */ @dots{} foo(); funcptr = foo; -@end example +@end smallexample Here the call to @code{foo()} will use the macro, but the function pointer will get the address of the real function. If the macro were to @@ -1287,11 +1332,11 @@ macro definition, that does not define a function-like macro, it defines an object-like macro whose expansion happens to begin with a pair of parentheses. -@example +@smallexample #define lang_init () c_init() lang_init() @expansion{} () c_init()() -@end example +@end smallexample The first two pairs of parentheses in this expansion come from the macro. The third is the pair that was originally after the macro @@ -1323,12 +1368,12 @@ macro body.) As an example, here is a macro that computes the minimum of two numeric values, as it is defined in many C programs, and some uses. -@example +@smallexample #define min(X, Y) ((X) < (Y) ? (X) : (Y)) x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b)); y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2)); z = min(a + 28, *p); @expansion{} z = ((a + 28) < (*p) ? (a + 28) : (*p)); -@end example +@end smallexample @noindent (In this small example you can already see several of the dangers of @@ -1341,9 +1386,9 @@ such parentheses does not end the argument. However, there is no requirement for square brackets or braces to balance, and they do not prevent a comma from separating arguments. Thus, -@example +@smallexample macro (array[x = y, x + 1]) -@end example +@end smallexample @noindent passes two arguments to @code{macro}: @code{array[x = y} and @code{x + @@ -1361,20 +1406,20 @@ Prescan}, for detailed discussion. For example, @code{min (min (a, b), c)} is first expanded to -@example +@smallexample min (((a) < (b) ? (a) : (b)), (c)) -@end example +@end smallexample @noindent and then to -@example +@smallexample @group ((((a) < (b) ? (a) : (b))) < (c) ? (((a) < (b) ? (a) : (b))) : (c)) @end group -@end example +@end smallexample @noindent (Line breaks shown here for clarity would not actually be generated.) @@ -1386,7 +1431,7 @@ You cannot leave out arguments entirely; if a macro takes two arguments, there must be exactly one comma at the top level of its argument list. Here are some silly examples using @code{min}: -@example +@smallexample min(, b) @expansion{} (( ) < (b) ? ( ) : (b)) min(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( )) min(,) @expansion{} (( ) < ( ) ? ( ) : ( )) @@ -1394,7 +1439,7 @@ min((,),) @expansion{} (((,)) < ( ) ? ((,)) : ( )) min() @error{} macro "min" requires 2 arguments, but only 1 given min(,,) @error{} macro "min" passed 3 arguments, but takes just 2 -@end example +@end smallexample Whitespace is not a preprocessing token, so if a macro @code{foo} takes one argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an @@ -1406,10 +1451,10 @@ empty argument was required. Macro parameters appearing inside string literals are not replaced by their corresponding actual arguments. -@example +@smallexample #define foo(x) x, "x" foo(bar) @expansion{} bar, "x" -@end example +@end smallexample @node Stringification @section Stringification @@ -1433,7 +1478,7 @@ long string. Here is an example of a macro definition that uses stringification: -@example +@smallexample @group #define WARN_IF(EXP) \ do @{ if (EXP) \ @@ -1443,7 +1488,7 @@ WARN_IF (x == 0); @expansion{} do @{ if (x == 0) fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0); @end group -@end example +@end smallexample @noindent The argument for @code{EXP} is substituted once, as-is, into the @@ -1476,7 +1521,7 @@ There is no way to convert a macro argument into a character constant. If you want to stringify the result of expansion of a macro argument, you have to use two levels of macros. -@example +@smallexample #define xstr(s) str(s) #define str(s) #s #define foo 4 @@ -1486,7 +1531,7 @@ xstr (foo) @expansion{} xstr (4) @expansion{} str (4) @expansion{} "4" -@end example +@end smallexample @code{s} is stringified when it is used in @code{str}, so it is not macro-expanded first. But @code{s} is an ordinary argument to @@ -1543,7 +1588,7 @@ Consider a C program that interprets named commands. There probably needs to be a table of commands, perhaps an array of structures declared as follows: -@example +@smallexample @group struct command @{ @@ -1560,7 +1605,7 @@ struct command commands[] = @dots{} @}; @end group -@end example +@end smallexample It would be cleaner not to have to give each command name twice, once in the string constant and once in the function name. A macro which takes the @@ -1568,7 +1613,7 @@ name of a command as an argument can make this unnecessary. The string constant can be created with stringification, and the function name by concatenating the argument with @samp{_command}. Here is how it is done: -@example +@smallexample #define COMMAND(NAME) @{ #NAME, NAME ## _command @} struct command commands[] = @@ -1577,7 +1622,7 @@ struct command commands[] = COMMAND (help), @dots{} @}; -@end example +@end smallexample @node Variadic Macros @section Variadic Macros @@ -1589,9 +1634,9 @@ A macro can be declared to accept a 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 eprintf(@dots{}) fprintf (stderr, __VA_ARGS__) -@end example +@end smallexample This kind of macro is called @dfn{variadic}. When the macro is invoked, all the tokens in its argument list after the last named argument (this @@ -1600,10 +1645,10 @@ argument}. This sequence of tokens replaces the identifier @code{@w{__VA_ARGS__}} in the macro body wherever it appears. Thus, we have this expansion: -@example +@smallexample eprintf ("%s:%d: ", input_file, lineno) @expansion{} fprintf (stderr, "%s:%d: ", input_file, lineno) -@end example +@end smallexample The variable argument is completely macro-expanded before it is inserted into the macro expansion, just like an ordinary argument. You may use @@ -1617,9 +1662,9 @@ this, as an extension. You may write an argument name immediately before the @samp{@dots{}}; that name is used for the variable argument. The @code{eprintf} macro above could be written -@example +@smallexample #define eprintf(args@dots{}) fprintf (stderr, args) -@end example +@end smallexample @noindent using this extension. You cannot use @code{@w{__VA_ARGS__}} and this @@ -1628,9 +1673,9 @@ extension in the same macro. You can have named arguments as well as variable arguments in a variadic macro. We could define @code{eprintf} like this, instead: -@example +@smallexample #define eprintf(format, @dots{}) fprintf (stderr, format, __VA_ARGS__) -@end example +@end smallexample @noindent This formulation looks more descriptive, but unfortunately it is less @@ -1640,26 +1685,26 @@ argument from the variable arguments. Furthermore, if you leave the variable argument empty, you will get a syntax error, because there will be an extra comma after the format string. -@example +@smallexample eprintf("success!\n", ); @expansion{} fprintf(stderr, "success!\n", ); -@end example +@end smallexample GNU CPP has a pair of extensions which deal with this problem. First, you are allowed to leave the variable argument out entirely: -@example +@smallexample eprintf ("success!\n") @expansion{} fprintf(stderr, "success!\n", ); -@end example +@end smallexample @noindent Second, the @samp{##} token paste operator has a special meaning when placed between a comma and a variable argument. If you write -@example +@smallexample #define eprintf(format, @dots{}) fprintf (stderr, format, ##__VA_ARGS__) -@end example +@end smallexample @noindent and the variable argument is left out when the @code{eprintf} macro is @@ -1667,10 +1712,10 @@ used, then the comma before the @samp{##} will be deleted. This does @emph{not} happen if you pass an empty argument, nor does it happen if the token preceding @samp{##} is anything other than a comma. -@example +@smallexample eprintf ("success!\n") @expansion{} fprintf(stderr, "success!\n"); -@end example +@end smallexample @noindent The above explanation is ambiguous about the case where the only macro @@ -1703,9 +1748,9 @@ previous versions of GCC, the token preceding the special @samp{##} must be a comma, and there must be white space between that comma and whatever comes immediately before it: -@example +@smallexample #define eprintf(format, args@dots{}) fprintf (stderr, format , ##args) -@end example +@end smallexample @noindent @xref{Differences from previous versions}, for the gory details. @@ -1758,12 +1803,12 @@ message to report an inconsistency detected by the program; the message can state the source line at which the inconsistency was detected. For example, -@example +@smallexample fprintf (stderr, "Internal error: " "negative string length " "%d at %s, line %d.", length, __FILE__, __LINE__); -@end example +@end smallexample An @samp{#include} directive changes the expansions of @code{__FILE__} and @code{__LINE__} to correspond to the included file. At the end of @@ -1849,7 +1894,8 @@ or a C++ compiler. This macro is similar to @code{__STDC_VERSION__}, in that it expands to a version number. A fully conforming implementation of the 1998 C++ standard will define this macro to @code{199711L}. The GNU C++ compiler is not yet fully conforming, so it uses @code{1} -instead. We hope to complete our implementation in the near future. +instead. It is hoped to complete the implementation of standard C++ +in the near future. @item __OBJC__ This macro is defined, with value 1, when the Objective-C compiler is in @@ -1897,26 +1943,26 @@ minor version and patch level are reset. If you wish to use the predefined macros directly in the conditional, you will need to write it like this: -@example +@smallexample /* @r{Test for GCC > 3.2.0} */ #if __GNUC__ > 3 || \ (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ (__GNUC_MINOR__ == 2 && \ __GNUC_PATCHLEVEL__ > 0)) -@end example +@end smallexample @noindent Another approach is to use the predefined macros to calculate a single number, then compare that against a threshold: -@example +@smallexample #define GCC_VERSION (__GNUC__ * 10000 \ + __GNUC_MINOR__ * 100 \ + __GNUC_PATCHLEVEL__) @dots{} /* @r{Test for GCC > 3.2.0} */ #if GCC_VERSION > 30200 -@end example +@end smallexample @noindent Many people find this form easier to understand. @@ -2022,7 +2068,7 @@ this macro directly; instead, include the appropriate headers. @itemx __INT_MAX__ @itemx __LONG_MAX__ @itemx __LONG_LONG_MAX__ -Defined to the maximum value of the @code{signed char}, @code{wchar_t}, +Defined to the maximum value of the @code{signed char}, @code{wchar_t}, @code{signed short}, @code{signed int}, @code{signed long}, and @code{signed long long} types respectively. They exist to make the standard header given numerical limits @@ -2041,7 +2087,7 @@ runtime is used, this macro is not defined, so that you can use this macro to determine which runtime (NeXT or GNU) is being used. @item __LP64__ -@item _LP64 +@itemx _LP64 These macros are defined, with value 1, if (and only if) the compilation is for a target where @code{long int} and pointer both use 64-bits and @code{int} uses 32-bit. @@ -2131,12 +2177,12 @@ macro is function-like. It is an error if anything appears on the line after the macro name. @samp{#undef} has no effect if the name is not a macro. -@example +@smallexample #define FOO 4 x = FOO; @expansion{} x = 4; #undef FOO x = FOO; @expansion{} x = FOO; -@end example +@end smallexample Once a macro has been undefined, that identifier may be @dfn{redefined} as a macro by a subsequent @samp{#define} directive. The new definition @@ -2156,19 +2202,19 @@ count as whitespace. @noindent These definitions are effectively the same: -@example +@smallexample #define FOUR (2 + 2) #define FOUR (2 + 2) #define FOUR (2 /* two */ + 2) -@end example +@end smallexample @noindent but these are not: -@example +@smallexample #define FOUR (2 + 2) #define FOUR ( 2+2 ) #define FOUR (2 * 2) #define FOUR(score,and,seven,years,ago) (2 + 2) -@end example +@end smallexample If a macro is redefined with a definition that is not effectively the same as the old one, the preprocessor issues a warning and changes the @@ -2249,25 +2295,25 @@ the input file, for more macro calls. It is possible to piece together a macro call coming partially from the macro body and partially from the arguments. For example, -@example +@smallexample #define twice(x) (2*(x)) #define call_with_1(x) x(1) call_with_1 (twice) @expansion{} twice(1) @expansion{} (2*(1)) -@end example +@end smallexample Macro definitions do not have to have balanced parentheses. By writing an unbalanced open parenthesis in a macro body, it is possible to create a macro call that begins inside the macro body but ends outside of it. For example, -@example +@smallexample #define strange(file) fprintf (file, "%s %d", @dots{} strange(stderr) p, 35) @expansion{} fprintf (stderr, "%s %d", p, 35) -@end example +@end smallexample The ability to piece together a macro call can be useful, but the use of unbalanced open parentheses in a macro body is just confusing, and @@ -2285,41 +2331,41 @@ way. Suppose you define a macro as follows, -@example +@smallexample #define ceil_div(x, y) (x + y - 1) / y -@end example +@end smallexample @noindent whose purpose is to divide, rounding up. (One use for this operation is to compute how many @code{int} objects are needed to hold a certain number of @code{char} objects.) Then suppose it is used as follows: -@example +@smallexample a = ceil_div (b & c, sizeof (int)); @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int); -@end example +@end smallexample @noindent This does not do what is intended. The operator-precedence rules of C make it equivalent to this: -@example +@smallexample a = (b & (c + sizeof (int) - 1)) / sizeof (int); -@end example +@end smallexample @noindent What we want is this: -@example +@smallexample a = ((b & c) + sizeof (int) - 1)) / sizeof (int); -@end example +@end smallexample @noindent Defining the macro as -@example +@smallexample #define ceil_div(x, y) ((x) + (y) - 1) / (y) -@end example +@end smallexample @noindent provides the desired result. @@ -2329,9 +2375,9 @@ ceil_div(1, 2)}. That has the appearance of a C expression that would compute the size of the type of @code{ceil_div (1, 2)}, but in fact it means something very different. Here is what it expands to: -@example +@smallexample sizeof ((1) + (2) - 1) / (2) -@end example +@end smallexample @noindent This would take the size of an integer and divide it by two. The @@ -2341,9 +2387,9 @@ was intended to be inside. Parentheses around the entire macro definition prevent such problems. Here, then, is the recommended way to define @code{ceil_div}: -@example +@smallexample #define ceil_div(x, y) (((x) + (y) - 1) / (y)) -@end example +@end smallexample @node Swallowing the Semicolon @subsection Swallowing the Semicolon @@ -2354,13 +2400,13 @@ statement. Consider, for example, the following macro, that advances a pointer (the argument @code{p} says where to find it) across whitespace characters: -@example +@smallexample #define SKIP_SPACES(p, limit) \ @{ char *lim = (limit); \ while (p < lim) @{ \ if (*p++ != ' ') @{ \ p--; break; @}@}@} -@end example +@end smallexample @noindent Here backslash-newline is used to split the macro definition, which must @@ -2377,11 +2423,11 @@ like a function call, writing a semicolon afterward, as in This can cause trouble before @code{else} statements, because the semicolon is actually a null statement. Suppose you write -@example +@smallexample if (*p != 0) SKIP_SPACES (p, lim); else @dots{} -@end example +@end smallexample @noindent The presence of two statements---the compound statement and a null @@ -2391,20 +2437,20 @@ makes invalid C code. The definition of the macro @code{SKIP_SPACES} can be altered to solve this problem, using a @code{do @dots{} while} statement. Here is how: -@example +@smallexample #define SKIP_SPACES(p, limit) \ do @{ char *lim = (limit); \ while (p < lim) @{ \ if (*p++ != ' ') @{ \ p--; break; @}@}@} \ while (0) -@end example +@end smallexample Now @code{SKIP_SPACES (p, lim);} expands into -@example +@smallexample do @{@dots{}@} while (0); -@end example +@end smallexample @noindent which is one statement. The loop executes exactly once; most compilers @@ -2417,23 +2463,23 @@ generate no extra code for it. @cindex unsafe macros Many C programs define a macro @code{min}, for ``minimum'', like this: -@example +@smallexample #define min(X, Y) ((X) < (Y) ? (X) : (Y)) -@end example +@end smallexample When you use this macro with an argument containing a side effect, as shown here, -@example +@smallexample next = min (x + y, foo (z)); -@end example +@end smallexample @noindent it expands as follows: -@example +@smallexample next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); -@end example +@end smallexample @noindent where @code{x + y} has been substituted for @code{X} and @code{foo (z)} @@ -2451,12 +2497,12 @@ computes the value of @code{foo (z)} only once. The C language offers no standard way to do this, but it can be done with GNU extensions as follows: -@example +@smallexample #define min(X, Y) \ (@{ typeof (X) x_ = (X); \ typeof (Y) y_ = (Y); \ (x_ < y_) ? x_ : y_; @}) -@end example +@end smallexample The @samp{(@{ @dots{} @})} notation produces a compound statement that acts as an expression. Its value is the value of its last statement. @@ -2470,7 +2516,7 @@ careful when @emph{using} the macro @code{min}. For example, you can calculate the value of @code{foo (z)}, save it in a variable, and use that variable in @code{min}: -@example +@smallexample @group #define min(X, Y) ((X) < (Y) ? (X) : (Y)) @dots{} @@ -2479,7 +2525,7 @@ that variable in @code{min}: next = min (x + y, tem); @} @end group -@end example +@end smallexample @noindent (where we assume that @code{foo} returns type @code{int}). @@ -2493,11 +2539,11 @@ definition. Recall that all macro definitions are rescanned for more macros to replace. If the self-reference were considered a use of the macro, it would produce an infinitely large expansion. To prevent this, the self-reference is not considered a macro call. It is passed into -the preprocessor output unchanged. Let's consider an example: +the preprocessor output unchanged. Consider an example: -@example +@smallexample #define foo (4 + foo) -@end example +@end smallexample @noindent where @code{foo} is also a variable in your program. @@ -2520,9 +2566,9 @@ of the variable @code{foo}, whereas in fact the value is four greater. One common, useful use of self-reference is to create a macro which expands to itself. If you write -@example +@smallexample #define EPERM EPERM -@end example +@end smallexample @noindent then the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is @@ -2536,15 +2582,15 @@ If a macro @code{x} expands to use a macro @code{y}, and the expansion of self-reference} of @code{x}. @code{x} is not expanded in this case either. Thus, if we have -@example +@smallexample #define x (4 + y) #define y (2 * x) -@end example +@end smallexample @noindent then @code{x} and @code{y} expand as follows: -@example +@smallexample @group x @expansion{} (4 + y) @expansion{} (4 + (2 * x)) @@ -2552,7 +2598,7 @@ x @expansion{} (4 + y) y @expansion{} (2 * x) @expansion{} (2 * (4 + y)) @end group -@end example +@end smallexample @noindent Each macro is expanded when it appears in the definition of the other @@ -2613,12 +2659,12 @@ concatenate its expansion, you can do that by causing one macro to call another macro that does the stringification or concatenation. For instance, if you have -@example +@smallexample #define AFTERX(x) X_ ## x #define XAFTERX(x) AFTERX(x) #define TABLESIZE 1024 #define BUFSIZE TABLESIZE -@end example +@end smallexample then @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and @code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to @@ -2630,11 +2676,11 @@ Macros used in arguments, whose expansions contain unshielded commas. This can cause a macro expanded on the second scan to be called with the wrong number of arguments. Here is an example: -@example +@smallexample #define foo a,b #define bar(x) lose(x) #define lose(x) (1 + (x)) -@end example +@end smallexample We would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which would then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)} @@ -2643,11 +2689,11 @@ requires a single argument. In this case, the problem is easily solved by the same parentheses that ought to be used to prevent misnesting of arithmetic operations: -@example +@smallexample #define foo (a,b) @exdent or #define bar(x) lose((x)) -@end example +@end smallexample The extra pair of parentheses prevents the comma in @code{foo}'s definition from being interpreted as an argument separator. @@ -2666,13 +2712,13 @@ different to the line containing the argument causing the problem. Here is an example illustrating this: -@example +@smallexample #define ignore_second_arg(a,b,c) a; c ignore_second_arg (foo (), ignored (), syntax error); -@end example +@end smallexample @noindent The syntax error triggered by the tokens @code{syntax error} results in @@ -2773,7 +2819,7 @@ directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. The simplest sort of conditional is -@example +@smallexample @group #ifdef @var{MACRO} @@ -2781,7 +2827,7 @@ The simplest sort of conditional is #endif /* @var{MACRO} */ @end group -@end example +@end smallexample @cindex conditional group This block is called a @dfn{conditional group}. @var{controlled text} @@ -2854,7 +2900,7 @@ automated by a tool such as @command{autoconf}, or done by hand. The @samp{#if} directive allows you to test the value of an arithmetic expression, rather than the mere existence of one macro. Its syntax is -@example +@smallexample @group #if @var{expression} @@ -2862,7 +2908,7 @@ expression, rather than the mere existence of one macro. Its syntax is #endif /* @var{expression} */ @end group -@end example +@end smallexample @var{expression} is a C expression of integer type, subject to stringent restrictions. It may contain @@ -2915,9 +2961,6 @@ expression, and may give different results in some cases. If the value comes out to be nonzero, the @samp{#if} succeeds and the @var{controlled text} is included; otherwise it is skipped. -If @var{expression} is not correctly formed, GCC issues an error and -treats the conditional as having failed. - @node Defined @subsection Defined @@ -2932,9 +2975,9 @@ defined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}. @code{defined} is useful when you wish to test more than one macro for existence at once. For example, -@example +@smallexample #if defined (__vax__) || defined (__ns16000__) -@end example +@end smallexample @noindent would succeed if either of the names @code{__vax__} or @@ -2942,9 +2985,9 @@ would succeed if either of the names @code{__vax__} or Conditionals written like this: -@example +@smallexample #if defined BUFSIZE && BUFSIZE >= 1024 -@end example +@end smallexample @noindent can generally be simplified to just @code{@w{#if BUFSIZE >= 1024}}, @@ -2965,7 +3008,7 @@ The @samp{#else} directive can be added to a conditional to provide alternative text to be used if the condition fails. This is what it looks like: -@example +@smallexample @group #if @var{expression} @var{text-if-true} @@ -2973,7 +3016,7 @@ looks like: @var{text-if-false} #endif /* Not @var{expression} */ @end group -@end example +@end smallexample @noindent If @var{expression} is nonzero, the @var{text-if-true} is included and @@ -2989,7 +3032,7 @@ You can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too. One common case of nested conditionals is used to check for more than two possible alternatives. For example, you might have -@example +@smallexample #if X == 1 @dots{} #else /* X != 1 */ @@ -2999,12 +3042,12 @@ possible alternatives. For example, you might have @dots{} #endif /* X != 2 */ #endif /* X != 1 */ -@end example +@end smallexample Another conditional directive, @samp{#elif}, allows this to be abbreviated as follows: -@example +@smallexample #if X == 1 @dots{} #elif X == 2 @@ -3012,7 +3055,7 @@ abbreviated as follows: #else /* X != 2 and X != 1*/ @dots{} #endif /* X != 2 and X != 1*/ -@end example +@end smallexample @samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the middle of a conditional group and subdivides it; it does not require a @@ -3072,23 +3115,23 @@ combination of parameters which you know the program does not properly support. For example, if you know that the program will not run properly on a VAX, you might write -@example +@smallexample @group #ifdef __vax__ #error "Won't work on VAXen. See comments at get_last_object." #endif @end group -@end example +@end smallexample If you have several configuration parameters that must be set up by the installation in a consistent way, you can use conditionals to detect an inconsistency and report it with @samp{#error}. For example, -@example +@smallexample #if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO) #error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP." #endif -@end example +@end smallexample @findex #warning The directive @samp{#warning} is like @samp{#error}, but causes the @@ -3222,18 +3265,18 @@ literal. It is destringized, by replacing all @samp{\\} with a single processed as if it had appeared as the right hand side of a @samp{#pragma} directive. For example, -@example +@smallexample _Pragma ("GCC dependency \"parse.y\"") -@end example +@end smallexample @noindent has the same effect as @code{#pragma GCC dependency "parse.y"}. The same effect could be achieved using macros, for example -@example +@smallexample #define DO_PRAGMA(x) _Pragma (#x) DO_PRAGMA (GCC dependency "parse.y") -@end example +@end smallexample The standard is unclear on where a @code{_Pragma} operator can appear. The preprocessor does not accept it within a preprocessing conditional @@ -3255,10 +3298,10 @@ other file is searched for using the normal include search path. Optional trailing text can be used to give more information in the warning message. -@example +@smallexample #pragma GCC dependency "parse.y" #pragma GCC dependency "/usr/include/time.h" rerun fixincludes -@end example +@end smallexample @item #pragma GCC poison Sometimes, there is an identifier that you want to remove completely @@ -3268,10 +3311,10 @@ enforce this, you can @dfn{poison} the identifier with this pragma. poison. If any of those identifiers appears anywhere in the source after the directive, it is a hard error. For example, -@example +@smallexample #pragma GCC poison printf sprintf fprintf sprintf(some_string, "hello"); -@end example +@end smallexample @noindent will produce an error. @@ -3283,11 +3326,11 @@ about system headers defining macros that use it. For example, -@example +@smallexample #define strrchr rindex #pragma GCC poison rindex strrchr(some_string, 'h'); -@end example +@end smallexample @noindent will not produce an error. @@ -3356,9 +3399,9 @@ necessary to prevent an accidental token paste. Source file name and line number information is conveyed by lines of the form -@example +@smallexample # @var{linenum} @var{filename} @var{flags} -@end example +@end smallexample @noindent These are called @dfn{linemarkers}. They are inserted as needed into @@ -3706,8 +3749,30 @@ and stick to it. @item The mapping of physical source file multi-byte characters to the execution character set. -Currently, GNU cpp only supports character sets that are strict supersets -of ASCII, and performs no translation of characters. +Currently, CPP requires its input to be ASCII or UTF-8. The execution +character set may be controlled by the user, with the +@code{-ftarget-charset} and @code{-ftarget-wide-charset} options. + +@item Identifier characters. +@anchor{Identifier characters} + +The C and C++ standards allow identifiers to be composed of @samp{_} +and the alphanumeric characters. C++ and C99 also allow universal +character names (not implemented in GCC), and C99 further permits +implementation-defined characters. + +GCC allows the @samp{$} character in identifiers as an extension for +most targets. This is true regardless of the @option{std=} switch, +since this extension cannot conflict with standards-conforming +programs. When preprocessing assembler, however, dollars are not +identifier characters by default. + +Currently the targets that by default do not permit @samp{$} are AVR, +IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX and +BeOS operating systems. + +You can override the default with @option{-fdollars-in-identifiers} or +@option{fno-dollars-in-identifiers}. @xref{fdollars-in-identifiers}. @item Non-empty sequences of whitespace characters. @@ -3765,10 +3830,10 @@ pragmas. CPP has a small number of internal limits. This section lists the limits which the C standard requires to be no lower than some minimum, -and all the others we are aware of. We intend there to be as few limits +and all the others known. It is intended that there should be as few limits as possible. If you encounter an undocumented or inconvenient limit, -please report that to us as a bug. (See the section on reporting bugs in -the GCC manual.) +please report that as a bug. @xref{Bugs, , Reporting Bugs, gcc, Using +the GNU Compiler Collection (GCC)}. Where we say something is limited @dfn{only by available memory}, that means that internal data structures impose no intrinsic limit, and space @@ -3857,9 +3922,9 @@ all. @cindex predicates An assertion looks like this: -@example +@smallexample #@var{predicate} (@var{answer}) -@end example +@end smallexample @noindent @var{predicate} must be a single identifier. @var{answer} can be any @@ -3875,26 +3940,26 @@ To test an assertion, you write it in an @samp{#if}. For example, this conditional succeeds if either @code{vax} or @code{ns16000} has been asserted as an answer for @code{machine}. -@example +@smallexample #if #machine (vax) || #machine (ns16000) -@end example +@end smallexample @noindent You can test whether @emph{any} answer is asserted for a predicate by omitting the answer in the conditional: -@example +@smallexample #if #machine -@end example +@end smallexample @findex #assert Assertions are made with the @samp{#assert} directive. Its sole argument is the assertion to make, without the leading @samp{#} that identifies assertions in conditionals. -@example +@smallexample #assert @var{predicate} (@var{answer}) -@end example +@end smallexample @noindent You may make several assertions with the same predicate and different @@ -3910,9 +3975,9 @@ answer which was specified on the @samp{#unassert} line; other answers for that predicate remain true. You can cancel an entire predicate by leaving out the answer: -@example +@smallexample #unassert @var{predicate} -@end example +@end smallexample @noindent In either form, if no such assertion has been made, @samp{#unassert} has @@ -4066,7 +4131,9 @@ without notice. cpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}] [@option{-I}@var{dir}@dots{}] [@option{-W}@var{warn}@dots{}] [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}] - [@option{-MP}] [@option{-MQ} @var{target}@dots{}] [@option{-MT} @var{target}@dots{}] + [@option{-MP}] [@option{-MQ} @var{target}@dots{}] + [@option{-MT} @var{target}@dots{}] + [@option{-P}] [@option{-fno-working-directory}] [@option{-x} @var{language}] [@option{-std=}@var{standard}] @var{infile} @var{outfile} @@ -4119,7 +4186,7 @@ Note that you can also specify places to search using options such as @option{-M} (@pxref{Invocation}). These take precedence over environment variables, which in turn take precedence over the configuration of GCC@. - + @include cppenv.texi @c man end diff --git a/contrib/gcc/doc/cppenv.texi b/contrib/gcc/doc/cppenv.texi index 7a913f1..bb29cb2 100644 --- a/contrib/gcc/doc/cppenv.texi +++ b/contrib/gcc/doc/cppenv.texi @@ -1,4 +1,4 @@ -@c Copyright (c) 1999, 2000, 2001, 2002 +@c Copyright (c) 1999, 2000, 2001, 2002, 2004 @c Free Software Foundation, Inc. @c This is part of the CPP and GCC manuals. @c For copying conditions, see the file gcc.texi. @@ -20,7 +20,7 @@ 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 Windows-based targets it is a +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 diff --git a/contrib/gcc/doc/cppinternals.texi b/contrib/gcc/doc/cppinternals.texi index 3f3d9af..9f5863c 100644 --- a/contrib/gcc/doc/cppinternals.texi +++ b/contrib/gcc/doc/cppinternals.texi @@ -16,7 +16,7 @@ @ifinfo This file documents the internals of the GNU C Preprocessor. -Copyright 2000, 2001, 2002 Free Software Foundation, Inc. +Copyright 2000, 2001, 2002, 2004 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -47,7 +47,7 @@ into another language, under the above conditions for modified versions. @page @vskip 0pt plus 1filll @c man begin COPYRIGHT -Copyright @copyright{} 2000, 2001, 2002 +Copyright @copyright{} 2000, 2001, 2002, 2004 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of @@ -226,7 +226,7 @@ foo @end smallexample This is a good example of the subtlety of getting token spacing correct -in the preprocessor; there are plenty of tests in the test suite for +in the preprocessor; there are plenty of tests in the testsuite for corner cases like this. The lexer is written to treat each of @samp{\r}, @samp{\n}, @samp{\r\n} @@ -368,8 +368,8 @@ chaining a new token run on to the end of the existing one. The tokens forming a macro's replacement list are collected by the @code{#define} handler, and placed in storage that is only freed by -@code{cpp_destroy}. So if a macro is expanded in our line of tokens, -the pointers to the tokens of its expansion that we return will always +@code{cpp_destroy}. So if a macro is expanded in the line of tokens, +the pointers to the tokens of its expansion that are returned will always remain valid. However, macros are a little trickier than that, since they give rise to three sources of fresh tokens. They are the built-in macros like @code{__LINE__}, and the @samp{#} and @samp{##} operators @@ -640,8 +640,8 @@ is safe. @cindex spacing @cindex token spacing -First, let's look at an issue that only concerns the stand-alone -preprocessor: we want to guarantee that re-reading its preprocessed +First, consider an issue that only concerns the stand-alone +preprocessor: there needs to be a guarantee that re-reading its preprocessed output results in an identical token stream. Without taking special measures, this might not be the case because of macro substitution. For example: @@ -670,7 +670,7 @@ expansion, but accidental pasting can occur in many places: both before and after each macro replacement, each argument replacement, and additionally each token created by the @samp{#} and @samp{##} operators. -Let's look at how the preprocessor gets whitespace output correct +Look at how the preprocessor gets whitespace output correct normally. The @code{cpp_token} structure contains a flags byte, and one of those flags is @code{PREV_WHITE}. This is flagged by the lexer, and indicates that the token was preceded by whitespace of some form other @@ -719,11 +719,11 @@ a macro's first replacement token expands straight into another macro. Here, two padding tokens are generated with sources the @samp{foo} token between the brackets, and the @samp{bar} token from foo's replacement -list, respectively. Clearly the first padding token is the one we -should use, so our output code should contain a rule that the first +list, respectively. Clearly the first padding token is the one to +use, so the output code should contain a rule that the first padding token in a sequence is the one that matters. -But what if we happen to leave a macro expansion? Adjusting the above +But what if a macro expansion is left? Adjusting the above example slightly: @smallexample diff --git a/contrib/gcc/doc/cppopts.texi b/contrib/gcc/doc/cppopts.texi index 1cc688a..6e784de 100644 --- a/contrib/gcc/doc/cppopts.texi +++ b/contrib/gcc/doc/cppopts.texi @@ -1,4 +1,4 @@ -@c Copyright (c) 1999, 2000, 2001, 2002 +@c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004 @c Free Software Foundation, Inc. @c This is part of the CPP and GCC manuals. @c For copying conditions, see the file gcc.texi. @@ -17,10 +17,14 @@ Predefine @var{name} as a macro, with definition @code{1}. @item -D @var{name}=@var{definition} Predefine @var{name} as a macro, with definition @var{definition}. -There are no restrictions on the contents of @var{definition}, but 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. +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 will be 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 @@ -72,10 +76,12 @@ use @option{-o} to specify the output file. @item -Wall @opindex Wall -Turns on all optional warnings which are desirable for normal code. At -present this is @option{-Wcomment} and @option{-Wtrigraphs}. Note that -many of the preprocessor's warnings are on by default and have no -options to control them. +Turns on all optional warnings which are desirable for normal code. +At present this is @option{-Wcomment}, @option{-Wtrigraphs}, +@option{-Wmultichar} and a warning about integer promotion causing a +change of sign in @code{#if} expressions. Note that many of the +preprocessor's warnings are on by default and have no options to +control them. @item -Wcomment @itemx -Wcomments @@ -87,10 +93,17 @@ comment, or whenever a backslash-newline appears in a @samp{//} comment. @item -Wtrigraphs @opindex Wtrigraphs -Warn if any trigraphs are encountered. This option used to take effect -only if @option{-trigraphs} was also specified, but now works -independently. Warnings are not given for trigraphs within comments, as -they do not affect the meaning of the program. +@anchor{Wtrigraphs} +Most trigraphs in comments cannot affect the meaning of the program. +However, a trigraph that would form an escaped newline (@samp{??/} at +the end of a line) can, by changing where the comment begins or ends. +Therefore, only trigraphs that would form escaped newlines produce +warnings inside a comment. + +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 -Wtraditional @opindex Wtraditional @@ -214,9 +227,9 @@ This implies that the choice of angle brackets or double quotes in an header will appear in @option{-MM} dependency output. This is a slight change in semantics from GCC versions 3.0 and earlier. +@anchor{dashMF} @item -MF @var{file} @opindex MF -@anchor{-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 have sent @@ -246,11 +259,11 @@ files without updating the @file{Makefile} to match. This is typical output: -@example +@smallexample test.o: test.c test.h test.h: -@end example +@end smallexample @item -MT @var{target} @opindex MT @@ -266,9 +279,9 @@ argument to @option{-MT}, or use multiple @option{-MT} options. For example, @option{@w{-MT '$(objpfx)foo.o'}} might give -@example +@smallexample $(objpfx)foo.o: foo.c -@end example +@end smallexample @item -MQ @var{target} @opindex MQ @@ -276,9 +289,9 @@ $(objpfx)foo.o: foo.c Same as @option{-MT}, but it quotes any characters which are special to Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives -@example +@smallexample $$(objpfx)foo.o: foo.c -@end example +@end smallexample The default target is automatically quoted, as if it were given with @option{-MQ}. @@ -293,7 +306,7 @@ basename of the input file 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 -(but @pxref{-MF}), but if used without @option{-E}, each @option{-o} +(but @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 @@ -304,6 +317,17 @@ a dependency output file as a side-effect of the compilation process. Like @option{-MD} except mention only user header files, not system -header files. +@ifclear cppmanual +@item -fpch-deps +@opindex fpch-deps +When using precompiled headers (@pxref{Precompiled Headers}), this flag +will cause the dependency-output flags to also list the files from the +precompiled header's dependencies. If not specified only the +precompiled header would be listed and not the files that were used to +create it because those files are not consulted when a precompiled +header is used. + +@end ifclear @item -x c @itemx -x c++ @itemx -x objective-c @@ -436,8 +460,6 @@ Append @var{dir} to the prefix specified previously with path. @option{-iwithprefixbefore} puts it in the same place @option{-I} would; @option{-iwithprefix} puts it where @option{-idirafter} would. -Use of these options is discouraged. - @item -isystem @var{dir} @opindex isystem Search @var{dir} for header files, after all directories specified by @@ -448,6 +470,14 @@ is applied to the standard system directories. @xref{System Headers}. @end ifset +@item -fdollars-in-identifiers +@opindex fdollars-in-identifiers +@anchor{fdollars-in-identifiers} +Accept @samp{$} in identifiers. +@ifset cppmanual + @xref{Identifier characters}. +@end ifset + @item -fpreprocessed @opindex fpreprocessed Indicate to the preprocessor that the input file has already been @@ -470,6 +500,47 @@ 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 -fexec-charset=@var{charset} +@opindex fexec-charset +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 +Set the wide execution character set, used for wide string and +character constants. The default is UTF-32 or UTF-16, whichever +corresponds to the width of @code{wchar_t}. As with +@option{-ftarget-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 +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. + +@item -fworking-directory +@opindex fworking-directory +@opindex fno-working-directory +Enable generation of linemarkers in the preprocessor output that will +let the compiler know the current working directory at the time of +preprocessing. When this option is enabled, the preprocessor will +emit, after the initial linemarker, a second linemarker with the +current working directory followed by two slashes. GCC will use 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 -fno-show-column @opindex fno-show-column Do not print column numbers in diagnostics. This may be necessary if @@ -506,9 +577,9 @@ 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 -@example +@smallexample touch foo.h; cpp -dM foo.h -@end example +@end smallexample @noindent will show all the predefined macros. @@ -616,7 +687,9 @@ execution, and report the final form of the include path. @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. +@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 -version @itemx --version diff --git a/contrib/gcc/doc/extend.texi b/contrib/gcc/doc/extend.texi index f2aca2a..3785cee 100644 --- a/contrib/gcc/doc/extend.texi +++ b/contrib/gcc/doc/extend.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1988,1989,1992,1993,1994,1996,1998,1999,2000,2001,2002, 2003 +@c Copyright (C) 1988,1989,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003,2004 @c Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -253,7 +253,7 @@ The @code{register} specifier affects code generation only in these ways: @itemize @bullet @item -When used as part of the register variable extension, see +When used as part of the register variable extension, see @ref{Explicit Reg Vars}. @item @@ -424,7 +424,7 @@ extensions, accepted by GCC in C89 mode and in C++. @menu * Statement Exprs:: Putting statements and declarations inside expressions. -* Local Labels:: Labels local to a statement-expression. +* Local Labels:: Labels local to a block. * Labels as Values:: Getting pointers to labels, and computed gotos. * Nested Functions:: As in Algol and Pascal, lexical scoping of functions. * Constructing Calls:: Dispatching a call to another function. @@ -494,12 +494,12 @@ Recall that a compound statement is a sequence of statements surrounded by braces; in this construct, parentheses go around the braces. For example: -@example +@smallexample (@{ int y = foo (); int z; if (y > 0) z = y; else z = - y; z; @}) -@end example +@end smallexample @noindent is a valid (though slightly more complex than necessary) expression @@ -516,21 +516,21 @@ that they evaluate each operand exactly once). For example, the ``maximum'' function is commonly defined as a macro in standard C as follows: -@example +@smallexample #define max(a,b) ((a) > (b) ? (a) : (b)) -@end example +@end smallexample @noindent @cindex side effects, macro argument But this definition computes either @var{a} or @var{b} twice, with bad results if the operand has side effects. In GNU C, if you know the -type of the operands (here let's assume @code{int}), you can define +type of the operands (here taken as @code{int}), you can define the macro safely as follows: -@example +@smallexample #define maxint(a,b) \ (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) -@end example +@end smallexample Embedded statements are not allowed in constant expressions, such as the value of an enumeration constant, the width of a bit-field, or @@ -539,32 +539,46 @@ the initial value of a static variable. If you don't know the type of the operand, you can still do this, but you must use @code{typeof} (@pxref{Typeof}). -Statement expressions are not supported fully in G++, and their fate -there is unclear. (It is possible that they will become fully supported -at some point, or that they will be deprecated, or that the bugs that -are present will continue to exist indefinitely.) Presently, statement -expressions do not work well as default arguments. +In G++, the result value of a statement expression undergoes array and +function pointer decay, and is returned by value to the enclosing +expression. For instance, if @code{A} is a class, then -In addition, there are semantic issues with statement-expressions in -C++. If you try to use statement-expressions instead of inline -functions in C++, you may be surprised at the way object destruction is -handled. For example: +@smallexample + A a; -@example -#define foo(a) (@{int b = (a); b + 3; @}) -@end example + (@{a;@}).Foo () +@end smallexample @noindent -does not work the same way as: +will construct a temporary @code{A} object to hold the result of the +statement expression, and that will be used to invoke @code{Foo}. +Therefore the @code{this} pointer observed by @code{Foo} will not be the +address of @code{a}. + +Any temporaries created within a statement within a statement expression +will be destroyed at the statement's end. This makes statement +expressions inside macros slightly different from function calls. In +the latter case temporaries introduced during argument evaluation will +be destroyed at the end of the statement that includes the function +call. In the statement expression case they will be destroyed during +the statement expression. For instance, -@example -inline int foo(int a) @{ int b = a; return b + 3; @} -@end example +@smallexample +#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) +template<typename T> T function(T a) @{ T b = a; return b + 3; @} + +void foo () +@{ + macro (X ()); + function (X ()); +@} +@end smallexample @noindent -In particular, if the expression passed into @code{foo} involves the -creation of temporaries, the destructors for those temporaries will be -run earlier in the case of the macro than in the case of the function. +will have different places where temporaries are destroyed. For the +@code{macro} case, the temporary @code{X} will be destroyed just after +the initialization of @code{b}. In the @code{function} case that +temporary will be destroyed when the function returns. These considerations mean that it is probably a bad idea to use statement-expressions of this form in header files that are designed to @@ -577,41 +591,58 @@ bug.) @cindex local labels @cindex macros, local labels -Each statement expression is a scope in which @dfn{local labels} can be -declared. A local label is simply an identifier; you can jump to it -with an ordinary @code{goto} statement, but only from within the -statement expression it belongs to. +GCC allows you to declare @dfn{local labels} in any nested block +scope. A local label is just like an ordinary label, but you can +only reference it (with a @code{goto} statement, or by taking its +address) within the block in which it was declared. A local label declaration looks like this: -@example +@smallexample __label__ @var{label}; -@end example +@end smallexample @noindent or -@example +@smallexample __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; -@end example +@end smallexample -Local label declarations must come at the beginning of the statement -expression, right after the @samp{(@{}, before any ordinary -declarations. +Local label declarations must come at the beginning of the block, +before any ordinary declarations or statements. The label declaration defines the label @emph{name}, but does not define the label itself. You must do this in the usual way, with @code{@var{label}:}, within the statements of the statement expression. -The local label feature is useful because statement expressions are -often used in macros. If the macro contains nested loops, a @code{goto} -can be useful for breaking out of them. However, an ordinary label -whose scope is the whole function cannot be used: if the macro can be -expanded several times in one function, the label will be multiply -defined in that function. A local label avoids this problem. For -example: +The local label feature is useful for complex macros. If a macro +contains nested loops, a @code{goto} can be useful for breaking out of +them. However, an ordinary label whose scope is the whole function +cannot be used: if the macro can be expanded several times in one +function, the label will be multiply defined in that function. A +local label avoids this problem. For example: -@example +@smallexample +#define SEARCH(value, array, target) \ +do @{ \ + __label__ found; \ + typeof (target) _SEARCH_target = (target); \ + typeof (*(array)) *_SEARCH_array = (array); \ + int i, j; \ + int value; \ + for (i = 0; i < max; i++) \ + for (j = 0; j < max; j++) \ + if (_SEARCH_array[i][j] == _SEARCH_target) \ + @{ (value) = i; goto found; @} \ + (value) = -1; \ + found:; \ +@} while (0) +@end smallexample + +This could also be written using a statement-expression: + +@smallexample #define SEARCH(array, target) \ (@{ \ __label__ found; \ @@ -627,7 +658,10 @@ example: found: \ value; \ @}) -@end example +@end smallexample + +Local label declarations also make the labels they declare visible to +nested functions, if there are any. @xref{Nested Functions}, for details. @node Labels as Values @section Labels as Values @@ -641,11 +675,11 @@ You can get the address of a label defined in the current function value has type @code{void *}. This value is a constant and can be used wherever a constant of that type is valid. For example: -@example +@smallexample void *ptr; /* @r{@dots{}} */ ptr = &&foo; -@end example +@end smallexample To use these values, you need to be able to jump to one. This is done with the computed goto statement@footnote{The analogous feature in @@ -653,9 +687,9 @@ Fortran is called an assigned goto, but that name seems inappropriate in C, where one can do more than simply store label addresses in label variables.}, @code{goto *@var{exp};}. For example, -@example +@smallexample goto *ptr; -@end example +@end smallexample @noindent Any expression of type @code{void *} is allowed. @@ -663,15 +697,15 @@ Any expression of type @code{void *} is allowed. One way of using these constants is in initializing a static array that will serve as a jump table: -@example +@smallexample static void *array[] = @{ &&foo, &&bar, &&hack @}; -@end example +@end smallexample Then you can select a label with indexing, like this: -@example +@smallexample goto *array[i]; -@end example +@end smallexample @noindent Note that this does not check whether the subscript is in bounds---array @@ -693,11 +727,11 @@ never pass it as an argument. An alternate way to write the above example is -@example +@smallexample static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, &&hack - &&foo @}; goto *(&&foo + array[i]); -@end example +@end smallexample @noindent This is more friendly to code living in shared libraries, as it reduces @@ -715,7 +749,7 @@ A @dfn{nested function} is a function defined inside another function. name is local to the block where it is defined. For example, here we define a nested function named @code{square}, and call it twice: -@example +@smallexample @group foo (double a, double b) @{ @@ -724,14 +758,14 @@ foo (double a, double b) return square (a) + square (b); @} @end group -@end example +@end smallexample The nested function can access all the variables of the containing function that are visible at the point of its definition. This is called @dfn{lexical scoping}. For example, here we show a nested function which uses an inherited variable named @code{offset}: -@example +@smallexample @group bar (int *array, int offset, int size) @{ @@ -743,7 +777,7 @@ bar (int *array, int offset, int size) /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ @} @end group -@end example +@end smallexample Nested function definitions are permitted within functions in the places where variable definitions are allowed; that is, in any block, before @@ -752,7 +786,7 @@ the first statement in the block. It is possible to call the nested function from outside the scope of its name by storing its address or passing the address to another function: -@example +@smallexample hack (int *array, int size) @{ void store (int index, int value) @@ -760,7 +794,7 @@ hack (int *array, int size) intermediate (store, size); @} -@end example +@end smallexample Here, the function @code{intermediate} receives the address of @code{store} as an argument. If @code{intermediate} calls @code{store}, @@ -788,7 +822,7 @@ function (@pxref{Local Labels}). Such a jump returns instantly to the containing function, exiting the nested function which did the @code{goto} and any intermediate functions as well. Here is an example: -@example +@smallexample @group bar (int *array, int offset, int size) @{ @@ -812,14 +846,14 @@ bar (int *array, int offset, int size) return -1; @} @end group -@end example +@end smallexample A nested function always has internal linkage. Declaring one with @code{extern} is erroneous. If you need to declare the nested function before its definition, use @code{auto} (which is otherwise meaningless for function declarations). -@example +@smallexample bar (int *array, int offset, int size) @{ __label__ failure; @@ -833,7 +867,7 @@ bar (int *array, int offset, int size) @} /* @r{@dots{}} */ @} -@end example +@end smallexample @node Constructing Calls @section Constructing Function Calls @@ -850,6 +884,11 @@ and later return that value, without knowing what data type the function tried to return (as long as your caller expects that data type). +However, these built-in functions may interact badly with some +sophisticated features or other extensions of the language. It +is, therefore, not recommended to use them outside very simple +functions acting as mere forwarders for their arguments. + @deftypefn {Built-in Function} {void *} __builtin_apply_args () This built-in function returns a pointer to data describing how to perform a call with the same arguments as were passed @@ -899,9 +938,9 @@ construct acts semantically like a type name defined with @code{typedef}. There are two ways of writing the argument to @code{typeof}: with an expression or with a type. Here is an example with an expression: -@example +@smallexample typeof (x[0](1)) -@end example +@end smallexample @noindent This assumes that @code{x} is an array of pointers to functions; @@ -909,9 +948,9 @@ the type described is that of the values of the functions. Here is an example with a typename as the argument: -@example +@smallexample typeof (int *) -@end example +@end smallexample @noindent Here the type described is that of pointers to @code{int}. @@ -929,12 +968,12 @@ statements-within-expressions feature. Here is how the two together can be used to define a safe ``maximum'' macro that operates on any arithmetic type and evaluates each of its arguments exactly once: -@example +@smallexample #define max(a,b) \ (@{ typeof (a) _a = (a); \ typeof (b) _b = (b); \ _a > _b ? _a : _b; @}) -@end example +@end smallexample @cindex underscores in variables in macros @cindex @samp{_} in variables in macros @@ -956,45 +995,45 @@ Some more examples of the use of @code{typeof}: @item This declares @code{y} with the type of what @code{x} points to. -@example +@smallexample typeof (*x) y; -@end example +@end smallexample @item This declares @code{y} as an array of such values. -@example +@smallexample typeof (*x) y[4]; -@end example +@end smallexample @item This declares @code{y} as an array of pointers to characters: -@example +@smallexample typeof (typeof (char *)[4]) y; -@end example +@end smallexample @noindent It is equivalent to the following traditional C declaration: -@example +@smallexample char *y[4]; -@end example +@end smallexample To see the meaning of the declaration using @code{typeof}, and why it -might be a useful way to write, let's rewrite it with these macros: +might be a useful way to write, rewrite it with these macros: -@example +@smallexample #define pointer(T) typeof(T *) #define array(T, N) typeof(T [N]) -@end example +@end smallexample @noindent Now the declaration can be rewritten this way: -@example +@smallexample array (pointer (char), 4) y; -@end example +@end smallexample @noindent Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 @@ -1004,9 +1043,9 @@ pointers to @code{char}. @emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported a more limited extension which permitted one to write -@example +@smallexample typedef @var{T} = @var{expr}; -@end example +@end smallexample @noindent with the effect of declaring @var{T} to have the type of the expression @@ -1014,9 +1053,9 @@ with the effect of declaring @var{T} to have the type of the expression 3.0 and 3.2 will crash; 3.2.1 and later give an error). Code which relies on it should be rewritten to use @code{typeof}: -@example +@smallexample typedef typeof(@var{expr}) @var{T}; -@end example +@end smallexample @noindent This will work with all versions of GCC@. @@ -1035,39 +1074,41 @@ This will work with all versions of GCC@. Compound expressions, conditional expressions and casts are allowed as lvalues provided their operands are lvalues. This means that you can take -their addresses or store values into them. +their addresses or store values into them. All these extensions are +deprecated. -Standard C++ allows compound expressions and conditional expressions as -lvalues, and permits casts to reference type, so use of this extension -is deprecated for C++ code. +Standard C++ allows compound expressions and conditional expressions +as lvalues, and permits casts to reference type, so use of this +extension is not supported for C++ code. For example, a compound expression can be assigned, provided the last expression in the sequence is an lvalue. These two expressions are equivalent: -@example +@smallexample (a, b) += 5 a, (b += 5) -@end example +@end smallexample Similarly, the address of the compound expression can be taken. These two expressions are equivalent: -@example +@smallexample &(a, b) a, &b -@end example +@end smallexample A conditional expression is a valid lvalue if its type is not void and the true and false branches are both valid lvalues. For example, these two expressions are equivalent: -@example +@smallexample (a ? b : c) = 5 (a ? b = 5 : (c = 5)) -@end example +@end smallexample -A cast is a valid lvalue if its operand is an lvalue. A simple +A cast is a valid lvalue if its operand is an lvalue. This extension +is deprecated. A simple assignment whose left-hand side is a cast works by converting the right-hand side first to the specified type, then to the type of the inner left-hand side expression. After this is stored, the value is @@ -1075,20 +1116,20 @@ converted back to the specified type to become the value of the assignment. Thus, if @code{a} has type @code{char *}, the following two expressions are equivalent: -@example +@smallexample (int)a = 5 (int)(a = (char *)(int)5) -@end example +@end smallexample An assignment-with-arithmetic operation such as @samp{+=} applied to a cast performs the arithmetic using the type resulting from the cast, and then continues as in the previous case. Therefore, these two expressions are equivalent: -@example +@smallexample (int)a += 5 (int)(a = (char *)(int) ((int)a + 5)) -@end example +@end smallexample You cannot take the address of an lvalue cast, because the use of its address would not work out coherently. Suppose that @code{&(int)f} were @@ -1096,9 +1137,9 @@ permitted, where @code{f} has type @code{float}. Then the following statement would try to store an integer bit-pattern where a floating point number belongs: -@example +@smallexample *&(int)f = 1; -@end example +@end smallexample This is quite different from what @code{(int)f = 1} would do---that would convert 1 to floating point and store it. Rather than cause this @@ -1121,9 +1162,9 @@ expression. Therefore, the expression -@example +@smallexample x ? : y -@end example +@end smallexample @noindent has the value of @code{x} if that is nonzero; otherwise, the value of @@ -1131,9 +1172,9 @@ has the value of @code{x} if that is nonzero; otherwise, the value of This example is perfectly equivalent to -@example +@smallexample x ? x : y -@end example +@end smallexample @cindex side effect in ?: @cindex ?: side effect @@ -1271,7 +1312,7 @@ Zero-length arrays are allowed in GNU C@. They are very useful as the last element of a structure which is really a header for a variable-length object: -@example +@smallexample struct line @{ int length; char contents[0]; @@ -1280,7 +1321,7 @@ struct line @{ struct line *thisline = (struct line *) malloc (sizeof (struct line) + this_length); thisline->length = this_length; -@end example +@end smallexample In ISO C90, you would have to give @code{contents} a length of 1, which means either you waste space or complicate the argument to @code{malloc}. @@ -1324,7 +1365,7 @@ structure followed by an array of sufficient size to contain the data. I.e.@: in the following, @code{f1} is constructed as if it were declared like @code{f2}. -@example +@smallexample struct f1 @{ int x; int y[]; @} f1 = @{ 1, @{ 2, 3, 4 @} @}; @@ -1332,7 +1373,7 @@ struct f1 @{ struct f2 @{ struct f1 f1; int data[3]; @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; -@end example +@end smallexample @noindent The convenience of this extension is that @code{f1} has the desired @@ -1348,7 +1389,7 @@ with initialization of deeply nested arrays, we simply disallow any non-empty initialization except when the structure is the top-level object. For example: -@example +@smallexample struct foo @{ int x; int y[]; @}; struct bar @{ struct foo z; @}; @@ -1356,7 +1397,7 @@ struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.} -@end example +@end smallexample @node Empty Structures @section Structures With No Members @@ -1365,10 +1406,10 @@ struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.} GCC permits a C structure to have no members: -@example +@smallexample struct empty @{ @}; -@end example +@end smallexample The structure will have size zero. In C++, empty structures are part of the language. G++ treats empty structures as if they had a single @@ -1389,7 +1430,7 @@ a constant expression. The storage is allocated at the point of declaration and deallocated when the brace-level is exited. For example: -@example +@smallexample FILE * concat_fopen (char *s1, char *s2, char *mode) @{ @@ -1398,7 +1439,7 @@ concat_fopen (char *s1, char *s2, char *mode) strcat (str, s2); return fopen (str, mode); @} -@end example +@end smallexample @cindex scope of a variable length array @cindex variable-length array scope @@ -1422,13 +1463,13 @@ will also deallocate anything more recently allocated with @code{alloca}.) You can also use variable-length arrays as arguments to functions: -@example +@smallexample struct entry tester (int len, char data[len][len]) @{ /* @r{@dots{}} */ @} -@end example +@end smallexample The length of an array is computed once when the storage is allocated and is remembered for the scope of the array in case you access it with @@ -1437,13 +1478,13 @@ and is remembered for the scope of the array in case you access it with If you want to pass the array first and the length afterward, you can use a forward declaration in the parameter list---another GNU extension. -@example +@smallexample struct entry tester (int len; char data[len][len], int len) @{ /* @r{@dots{}} */ @} -@end example +@end smallexample @cindex parameter forward declaration The @samp{int len} before the semicolon is a @dfn{parameter forward @@ -1483,9 +1524,9 @@ GCC has long supported variadic macros, and used a different syntax that allowed you to give a name to the variable arguments just like any other argument. Here is an example: -@example +@smallexample #define debug(format, args...) fprintf (stderr, format, args) -@end example +@end smallexample This is in all ways equivalent to the ISO C example above, but arguably more readable and descriptive. @@ -1498,9 +1539,9 @@ entirely; but you are allowed to pass an empty argument. For example, this invocation is invalid in ISO C, because there is no comma after the string: -@example +@smallexample debug ("A message") -@end example +@end smallexample GNU CPP permits you to completely omit the variable arguments in this way. In the above examples, the compiler would complain, though since @@ -1551,7 +1592,7 @@ subscripted in C89 mode, though otherwise they do not decay to pointers outside C99 mode. For example, this is valid in GNU C though not valid in C89: -@example +@smallexample @group struct foo @{int a[4];@}; @@ -1562,7 +1603,7 @@ bar (int index) return f().a[index]; @} @end group -@end example +@end smallexample @node Pointer Arith @section Arithmetic on @code{void}- and Function-Pointers @@ -1591,13 +1632,13 @@ As in standard C++ and ISO C99, the elements of an aggregate initializer for an automatic variable are not required to be constant expressions in GNU C@. Here is an example of an initializer with run-time varying elements: -@example +@smallexample foo (float f, float g) @{ float beat_freqs[2] = @{ f-g, f+g @}; /* @r{@dots{}} */ @} -@end example +@end smallexample @node Compound Literals @section Compound Literals @@ -1617,26 +1658,26 @@ compound literals in C89 mode and in C++. Usually, the specified type is a structure. Assume that @code{struct foo} and @code{structure} are declared as shown: -@example +@smallexample struct foo @{int a; char b[2];@} structure; -@end example +@end smallexample @noindent Here is an example of constructing a @code{struct foo} with a compound literal: -@example +@smallexample structure = ((struct foo) @{x + y, 'a', 0@}); -@end example +@end smallexample @noindent This is equivalent to writing the following: -@example +@smallexample @{ struct foo temp = @{x + y, 'a', 0@}; structure = temp; @} -@end example +@end smallexample You can also construct an array. If all the elements of the compound literal are (made up of) simple constant expressions, suitable for use in @@ -1644,9 +1685,9 @@ initializers of objects of static storage duration, then the compound literal can be coerced to a pointer to its first element and used in such an initializer, as shown here: -@example +@smallexample char **foo = (char *[]) @{ "x", "y", "z" @}; -@end example +@end smallexample Compound literals for scalar types and union types are is also allowed, but then the compound literal is equivalent @@ -1661,19 +1702,19 @@ The initializer list of the compound literal must be constant. If the object being initialized has array type of unknown size, the size is determined by compound literal size. -@example +@smallexample static struct foo x = (struct foo) @{1, 'a', 'b'@}; static int y[] = (int []) @{1, 2, 3@}; static int z[] = (int [3]) @{1@}; -@end example +@end smallexample @noindent The above lines are equivalent to the following: -@example +@smallexample static struct foo x = @{1, 'a', 'b'@}; static int y[] = @{1, 2, 3@}; static int z[] = @{1, 0, 0@}; -@end example +@end smallexample @node Designated Inits @section Designated Initializers @@ -1694,16 +1735,16 @@ implemented in GNU C++. To specify an array index, write @samp{[@var{index}] =} before the element value. For example, -@example +@smallexample int a[6] = @{ [4] = 29, [2] = 15 @}; -@end example +@end smallexample @noindent is equivalent to -@example +@smallexample int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; -@end example +@end smallexample @noindent The index values must be constant expressions, even if the array being @@ -1717,9 +1758,9 @@ To initialize a range of elements to the same value, write @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU extension. For example, -@example +@smallexample int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; -@end example +@end smallexample @noindent If the value in it has side-effects, the side-effects will happen only once, @@ -1733,30 +1774,30 @@ In a structure initializer, specify the name of a field to initialize with @samp{.@var{fieldname} =} before the element value. For example, given the following structure, -@example +@smallexample struct point @{ int x, y; @}; -@end example +@end smallexample @noindent the following initialization -@example +@smallexample struct point p = @{ .y = yvalue, .x = xvalue @}; -@end example +@end smallexample @noindent is equivalent to -@example +@smallexample struct point p = @{ xvalue, yvalue @}; -@end example +@end smallexample Another syntax which has the same meaning, obsolete since GCC 2.5, is @samp{@var{fieldname}:}, as shown here: -@example +@smallexample struct point p = @{ y: yvalue, x: xvalue @}; -@end example +@end smallexample @cindex designators The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a @@ -1764,11 +1805,11 @@ The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a syntax) when initializing a union, to specify which element of the union should be used. For example, -@example +@smallexample union foo @{ int i; double d; @}; union foo f = @{ .d = 4 @}; -@end example +@end smallexample @noindent will convert 4 to a @code{double} to store it in the union using @@ -1781,26 +1822,26 @@ initialization of successive elements. Each initializer element that does not have a designator applies to the next consecutive element of the array or structure. For example, -@example +@smallexample int a[6] = @{ [1] = v1, v2, [4] = v4 @}; -@end example +@end smallexample @noindent is equivalent to -@example +@smallexample int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; -@end example +@end smallexample Labeling the elements of an array initializer is especially useful when the indices are characters or belong to an @code{enum} type. For example: -@example +@smallexample int whitespace[256] = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; -@end example +@end smallexample @cindex designator lists You can also write a series of @samp{.@var{fieldname}} and @@ -1817,7 +1858,7 @@ struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; If the same field is initialized multiple times, it will have value from the last initialization. If any such overridden initialization has side-effect, it is unspecified whether the side-effect happens or not. -Currently, gcc will discard them and issue a warning. +Currently, GCC will discard them and issue a warning. @node Case Ranges @section Case Ranges @@ -1827,9 +1868,9 @@ Currently, gcc will discard them and issue a warning. You can specify a range of consecutive values in a single @code{case} label, like this: -@example +@smallexample case @var{low} ... @var{high}: -@end example +@end smallexample @noindent This has the same effect as the proper number of individual @code{case} @@ -1837,24 +1878,24 @@ labels, one for each integer value from @var{low} to @var{high}, inclusive. This feature is especially useful for ranges of ASCII character codes: -@example +@smallexample case 'A' ... 'Z': -@end example +@end smallexample @strong{Be careful:} Write spaces around the @code{...}, for otherwise it may be parsed wrong when you use it with integer values. For example, write this: -@example +@smallexample case 1 ... 5: -@end example +@end smallexample @noindent rather than this: -@example +@smallexample case 1...5: -@end example +@end smallexample @node Cast to Union @section Cast to a Union Type @@ -1870,11 +1911,11 @@ normal casts. (@xref{Compound Literals}.) The types that may be cast to the union type are those of the members of the union. Thus, given the following union and variables: -@example +@smallexample union foo @{ int i; double d; @}; int x; double y; -@end example +@end smallexample @noindent both @code{x} and @code{y} can be cast to type @code{union foo}. @@ -1882,20 +1923,20 @@ both @code{x} and @code{y} can be cast to type @code{union foo}. Using the cast as the right-hand side of an assignment to a variable of union type is equivalent to storing in a member of the union: -@example +@smallexample union foo u; /* @r{@dots{}} */ u = (union foo) x @equiv{} u.i = x u = (union foo) y @equiv{} u.d = y -@end example +@end smallexample You can also use the union cast as a function argument: -@example +@smallexample void hack (union foo); /* @r{@dots{}} */ hack ((union foo) x); -@end example +@end smallexample @node Mixed Declarations @section Mixed Declarations and Code @@ -1907,12 +1948,12 @@ ISO C99 and ISO C++ allow declarations and code to be freely mixed within compound statements. As an extension, GCC also allows this in C89 mode. For example, you could do: -@example +@smallexample int i; /* @r{@dots{}} */ i++; int j = i + 2; -@end example +@end smallexample Each identifier is visible from where it is declared until the end of the enclosing block. @@ -1946,9 +1987,9 @@ attributes are currently defined for functions on all targets: @code{format}, @code{format_arg}, @code{no_instrument_function}, @code{section}, @code{constructor}, @code{destructor}, @code{used}, @code{unused}, @code{deprecated}, @code{weak}, @code{malloc}, -@code{alias}, and @code{nonnull}. Several other attributes are defined -for functions on particular target systems. Other attributes, including -@code{section} are supported for variables declarations +@code{alias}, @code{warn_unused_result} and @code{nonnull}. Several other +attributes are defined for functions on particular target systems. Other +attributes, including @code{section} are supported for variables declarations (@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}). You may also specify attributes with @samp{__} preceding and following @@ -1986,6 +2027,10 @@ would happen if @code{fatal} ever did return. This makes slightly better code. More importantly, it helps avoid spurious warnings of uninitialized variables. +The @code{noreturn} keyword does not affect the exceptional path when that +applies: a @code{noreturn}-marked function may still return to the caller +by throwing an exception. + Do not assume that registers saved by the calling function are restored before calling the @code{noreturn} function. @@ -2248,8 +2293,7 @@ These attributes are not currently implemented for Objective-C@. @item unused This attribute, attached to a function, means that the function is meant to be possibly unused. GCC will not produce a warning for this -function. GNU C++ does not currently support this attribute as -definitions without parameters are valid in C++. +function. @cindex @code{used} attribute. @item used @@ -2279,6 +2323,26 @@ results in a warning on line 3 but not line 2. The @code{deprecated} attribute can also be used for variables and types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) +@item warn_unused_result +@cindex @code{warn_unused_result} attribute +The @code{warn_unused_result} attribute causes a warning to be emitted +if a caller of the function with this attribute does not use its +return value. This is useful for functions where not checking +the result is either a security problem or always a bug, such as +@code{realloc}. + +@smallexample +int fn () __attribute__ ((warn_unused_result)); +int foo () +@{ + if (fn () < 0) return -1; + fn (); + return 0; +@} +@end smallexample + +results in warning on line 5. + @item weak @cindex @code{weak} attribute The @code{weak} attribute causes the declaration to be emitted as a weak @@ -2291,9 +2355,14 @@ and linker. @item malloc @cindex @code{malloc} attribute The @code{malloc} attribute is used to tell the compiler that a function -may be treated as if it were the malloc function. The compiler assumes -that calls to malloc result in pointers that cannot alias anything. +may be treated as if any non-@code{NULL} pointer it returns cannot +alias any other pointer valid when the function returns. This will often improve optimization. +Standard functions with this property include @code{malloc} and +@code{calloc}. @code{realloc}-like functions have this property as +long as the old pointer is never referred to (including comparing it +to the new pointer) after the function returns a non-@code{NULL} +value. @item alias ("@var{target}") @cindex @code{alias} attribute @@ -2325,7 +2394,7 @@ See the ELF gABI for complete details, but the short story is: @table @dfn @item default -Default visibility is the normal case for ELF. This value is +Default visibility is the normal case for ELF. This value is available for the visibility attribute to override other options that may change the assumed visibility of symbols. @@ -2343,11 +2412,11 @@ by another module. @item internal Internal visibility is like hidden visibility, but with additional processor specific semantics. Unless otherwise specified by the psABI, -gcc defines internal visibility to mean that the function is @emph{never} +GCC defines internal visibility to mean that the function is @emph{never} called from another module. Note that hidden symbols, while they cannot be referenced directly by other modules, can be referenced indirectly via function pointers. By indicating that a symbol cannot be called from -outside the module, gcc may for instance omit the load of a PIC register +outside the module, GCC may for instance omit the load of a PIC register since it is known that the calling function loaded the correct value. @end table @@ -2378,6 +2447,13 @@ On the Intel 386, the @code{stdcall} attribute causes the compiler to assume that the called function will pop off the stack space used to pass arguments, unless it takes a variable number of arguments. +@item fastcall +@cindex functions that pop the argument stack on the 386 +On the Intel 386, the @code{fastcall} attribute causes the compiler to +pass the first two arguments in the registers ECX and EDX. Subsequent +arguments are passed on the stack. The called function will pop the +arguments off the stack. If the number of arguments is variable all +arguments are pushed on the stack. @item cdecl @cindex functions that do pop the argument stack on the 386 @@ -2412,24 +2488,24 @@ instruction directly. @item function_vector @cindex calling functions through the function vector on the H8/300 processors -Use this attribute on the H8/300 and H8/300H to indicate that the specified +Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified function should be called through the function vector. Calling a function through the function vector will reduce code size, however; the function vector has a limited size (maximum 128 entries on the H8/300 -and 64 entries on the H8/300H) and shares space with the interrupt vector. +and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. You must use GAS and GLD from GNU binutils version 2.7 or later for this attribute to work correctly. @item interrupt @cindex interrupt handler functions -Use this attribute on the ARM, AVR, M32R/D and Xstormy16 ports to indicate +Use this attribute on the ARM, AVR, C4x, M32R/D and Xstormy16 ports to indicate that the specified function is an interrupt handler. The compiler will generate function entry and exit sequences suitable for use in an interrupt handler when this attribute is present. -Note, interrupt handlers for the H8/300, H8/300H and SH processors can -be specified via the @code{interrupt_handler} attribute. +Note, interrupt handlers for the m68k, H8/300, H8/300H, H8S, and SH processors +can be specified via the @code{interrupt_handler} attribute. Note, on the AVR, interrupts will be enabled inside the function. @@ -2443,9 +2519,9 @@ void f () __attribute__ ((interrupt ("IRQ"))); Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@. @item interrupt_handler -@cindex interrupt handler functions on the H8/300 and SH processors -Use this attribute on the H8/300, H8/300H and SH to indicate that the -specified function is an interrupt handler. The compiler will generate +@cindex interrupt handler functions on the m68k, H8/300 and SH processors +Use this attribute on the m68k, H8/300, H8/300H, H8S, and SH to indicate that +the specified function is an interrupt handler. The compiler will generate function entry and exit sequences suitable for use in an interrupt handler when this attribute is present. @@ -2462,13 +2538,13 @@ void f () __attribute__ ((interrupt_handler, @end smallexample @item trap_exit -Use this attribute on the SH for an @code{interrupt_handle} to return using +Use this attribute on the SH for an @code{interrupt_handler} to return using @code{trapa} instead of @code{rte}. This attribute expects an integer argument specifying the trap number to be used. @item eightbit_data -@cindex eight bit data on the H8/300 and H8/300H -Use this attribute on the H8/300 and H8/300H to indicate that the specified +@cindex eight bit data on the H8/300, H8/300H, and H8S +Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified variable should be placed into the eight bit data section. The compiler will generate more efficient code for certain operations on data in the eight bit data area. Note the eight bit data area is limited to @@ -2478,13 +2554,19 @@ You must use GAS and GLD from GNU binutils version 2.7 or later for this attribute to work correctly. @item tiny_data -@cindex tiny data section on the H8/300H -Use this attribute on the H8/300H to indicate that the specified +@cindex tiny data section on the H8/300H and H8S +Use this attribute on the H8/300H and H8S to indicate that the specified variable should be placed into the tiny data section. The compiler will generate more efficient code for loads and stores on data in the tiny data section. Note the tiny data area is limited to slightly under 32kbytes of data. +@item saveall +@cindex save all registers on the H8/300, H8/300H, and H8S +Use this attribute on the H8/300, H8/300H, and H8S to indicate that +all registers except the stack pointer should be saved in the prologue +regardless of whether they are used or not. + @item signal @cindex signal handler functions on the AVR processors Use this attribute on the AVR to indicate that the specified @@ -2494,16 +2576,18 @@ attribute is present. Interrupts will be disabled inside the function. @item naked @cindex function without a prologue/epilogue code -Use this attribute on the ARM, AVR and IP2K ports to indicate that the +Use this attribute on the ARM, AVR, C4x and IP2K ports to indicate that the specified function does not need prologue/epilogue sequences generated by the compiler. It is up to the programmer to provide these sequences. @item model (@var{model-name}) @cindex function addressability on the M32R/D -Use this attribute on the M32R/D to set the addressability of an object, -and of the code generated for a function. -The identifier @var{model-name} is one of @code{small}, @code{medium}, -or @code{large}, representing each of the code models. +@cindex variable addressability on the IA-64 + +On the M32R/D, use this attribute to set the addressability of an +object, and of the code generated for a function. The identifier +@var{model-name} is one of @code{small}, @code{medium}, or +@code{large}, representing each of the code models. Small model objects live in the lower 16MB of memory (so that their addresses can be loaded with the @code{ld24} instruction), and are @@ -2518,6 +2602,14 @@ compiler will generate @code{seth/add3} instructions to load their addresses), and may not be reachable with the @code{bl} instruction (the compiler will generate the much slower @code{seth/add3/jl} instruction sequence). +On IA-64, use this attribute to set the addressability of an object. +At present, the only supported identifier for @var{model-name} is +@code{small}, indicating addressability via ``small'' (22-bit) +addresses (so that their addresses can be loaded with the @code{addl} +instruction). Caveat: such addressing is by definition not position +independent and hence this attribute must not be used for objects +defined by shared libraries. + @item far @cindex functions which handle memory bank switching On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to @@ -2544,9 +2636,9 @@ option. @item dllimport @cindex @code{__declspec(dllimport)} -On Windows targets, the @code{dllimport} attribute causes the compiler +On Microsoft Windows targets, the @code{dllimport} attribute causes the compiler to reference a function or variable via a global pointer to a pointer -that is set up by the Windows dll library. The pointer name is formed by +that is set up by the Microsoft Windows dll library. The pointer name is formed by combining @code{_imp__} and the function or variable name. The attribute implies @code{extern} storage. @@ -2555,7 +2647,7 @@ attribute is applied to a symbol @emph{definition}, an error is reported. If a symbol previously declared @code{dllimport} is later defined, the attribute is ignored in subsequent references, and a warning is emitted. The attribute is also overridden by a subsequent declaration as -@code{dllexport}. +@code{dllexport}. When applied to C++ classes, the attribute marks non-inlined member functions and static data members as imports. However, the @@ -2564,14 +2656,14 @@ using thunks. On cygwin, mingw and arm-pe targets, @code{__declspec(dllimport)} is recognized as a synonym for @code{__attribute__ ((dllimport))} for -compatibility with other Windows compilers. +compatibility with other Microsoft Windows compilers. The use of the @code{dllimport} attribute on functions is not necessary, but provides a small performance benefit by eliminating a thunk in the dll. The use of the @code{dllimport} attribute on imported variables was required on older versions of GNU ld, but can now be avoided by passing the @option{--enable-auto-import} switch to ld. As with functions, using -the attribute for a variable eliminates a thunk in the dll. +the attribute for a variable eliminates a thunk in the dll. One drawback to using this attribute is that a pointer to a function or variable marked as dllimport cannot be used as a constant address. The @@ -2580,7 +2672,7 @@ attribute can be disabled for functions by setting the @item dllexport @cindex @code{__declspec(dllexport)} -On Windows targets the @code{dllexport} attribute causes the compiler to +On Microsoft Windows targets the @code{dllexport} attribute causes the compiler to provide a global pointer to a pointer in a dll, so that it can be referenced with the @code{dllimport} attribute. The pointer name is formed by combining @code{_imp__} and the function or variable name. @@ -2597,7 +2689,7 @@ out-of-class. On cygwin, mingw and arm-pe targets, @code{__declspec(dllexport)} is recognized as a synonym for @code{__attribute__ ((dllexport))} for -compatibility with other Windows compilers. +compatibility with other Microsoft Windows compilers. Alternative methods for including the symbol in the dll's export table are to use a .def file with an @code{EXPORTS} section or, with GNU ld, @@ -2698,14 +2790,18 @@ with the list being a single string constant. An @dfn{attribute specifier list} is a sequence of one or more attribute specifiers, not separated by any other tokens. -An attribute specifier list may appear after the colon following a +In GNU C, an attribute specifier list may appear after the colon following a label, other than a @code{case} or @code{default} label. The only attribute it makes sense to use after a label is @code{unused}. This feature is intended for code generated by programs which contains labels that may be unused but which is compiled with @option{-Wall}. It would not normally be appropriate to use in it human-written code, though it could be useful in cases where the code that jumps to the label is -contained within an @code{#ifdef} conditional. +contained within an @code{#ifdef} conditional. GNU C++ does not permit +such placement of attribute lists, as it is permissible for a +declaration, which could begin with an attribute list, to be labelled in +C++. Declarations cannot be labelled in C90 or C99, so the ambiguity +does not arise there. An attribute specifier list may appear as part of a @code{struct}, @code{union} or @code{enum} specifier. It may go either immediately @@ -2878,7 +2974,7 @@ to the function type. GNU C extends ISO C to allow a function prototype to override a later old-style non-prototype definition. Consider the following example: -@example +@smallexample /* @r{Use prototypes unless the compiler is old-fashioned.} */ #ifdef __STDC__ #define P(x) x @@ -2896,7 +2992,7 @@ isroot (x) /* ??? lossage here ??? */ @{ return x == 0; @} -@end example +@end smallexample Suppose the type @code{uid_t} happens to be @code{short}. ISO C does not allow this example, because subword arguments in old-style @@ -2914,7 +3010,7 @@ by a later old-style definition if the former type is the same as the latter type before promotion. Thus in GNU C the above example is equivalent to the following: -@example +@smallexample int isroot (uid_t); int @@ -2922,7 +3018,7 @@ isroot (uid_t x) @{ return x == 0; @} -@end example +@end smallexample @noindent GNU C++ does not support old-style function definitions, so this @@ -2983,9 +3079,9 @@ any minimum alignment specified with GCC's @code{__attribute__} extension (@pxref{Variable Attributes}). For example, after this declaration: -@example +@smallexample struct foo @{ int x; char y; @} foo1; -@end example +@end smallexample @noindent the value of @code{__alignof__ (foo1.y)} is 1, even though its actual @@ -3100,7 +3196,7 @@ The @code{common} attribute requests GCC to place a variable in ``common'' storage. The @code{nocommon} attribute requests the opposite -- to allocate space for it directly. -These attributes override the default chosen by the +These attributes override the default chosen by the @option{-fno-common} and @option{-fcommon} flags respectively. @item deprecated @@ -3145,13 +3241,13 @@ and one bit for a field, unless you specify a larger value with the Here is a structure in which the field @code{x} is packed, so that it immediately follows @code{a}: -@example +@smallexample struct foo @{ char a; int x[2] __attribute__ ((packed)); @}; -@end example +@end smallexample @item section ("@var{section-name}") @cindex @code{section} variable attribute @@ -3203,7 +3299,7 @@ section, consider using the facilities of the linker instead. @item shared @cindex @code{shared} variable attribute -On Windows, in addition to putting variable definitions in a named +On Microsoft Windows, in addition to putting variable definitions in a named section, the section can also be shared among all running copies of an executable or DLL@. For example, this small program defines shared data by putting it in a named section @code{shared} and marking the section @@ -3226,7 +3322,7 @@ You may only use the @code{shared} attribute along with @code{section} attribute with a fully initialized global definition because of the way linkers work. See @code{section} attribute for more information. -The @code{shared} attribute is only available on Windows@. +The @code{shared} attribute is only available on Microsoft Windows@. @item tls_model ("@var{tls_model}") @cindex @code{tls_model} attribute @@ -3284,6 +3380,19 @@ the @code{int}. @item weak The @code{weak} attribute is described in @xref{Function Attributes}. +@item dllimport +The @code{dllimport} attribute is described in @xref{Function Attributes}. + +@item dlexport +The @code{dllexport} attribute is described in @xref{Function Attributes}. + +@end table + +@subsection M32R/D Variable Attributes + +One attribute is currently defined for the M32R/D. + +@table @code @item model (@var{model-name}) @cindex variable addressability on the M32R/D Use this attribute on the M32R/D to set the addressability of an object. @@ -3296,19 +3405,30 @@ addresses can be loaded with the @code{ld24} instruction). Medium and large model objects may live anywhere in the 32-bit address space (the compiler will generate @code{seth/add3} instructions to load their addresses). +@end table -@item dllimport -The @code{dllimport} attribute is described in @xref{Function Attributes}. +@subsection i386 Variable Attributes -@item dlexport -The @code{dllexport} attribute is described in @xref{Function Attributes}. +Two attributes are currently defined for i386 configurations: +@code{ms_struct} and @code{gcc_struct} +@table @code +@item ms_struct +@itemx gcc_struct +@cindex @code{ms_struct} attribute +@cindex @code{gcc_struct} attribute + +If @code{packed} is used on a structure, or if bit-fields are used +it may be that the Microsoft ABI packs them differently +than GCC would normally pack them. Particularly when moving packed +data between functions compiled with GCC and the native Microsoft compiler +(either via function call or as data in a file), it may be necessary to access +either format. + +Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 +compilers to match the native Microsoft compiler. @end table -To specify multiple attributes, separate them by commas within the -double parentheses: for example, @samp{__attribute__ ((aligned (16), -packed))}. - @node Type Attributes @section Specifying Attributes of Types @cindex attribute of types @@ -3422,9 +3542,10 @@ in an @code{__attribute__} will still only provide you with 8 byte alignment. See your linker documentation for further information. @item packed -This attribute, attached to an @code{enum}, @code{struct}, or -@code{union} type definition, specifies that the minimum required memory -be used to represent the type. +This attribute, attached to @code{struct} or @code{union} type +definition, specifies that each member of the structure or union is +placed to minimize the memory required. When attached to an @code{enum} +definition, it indicates that the smallest integral type should be used. @opindex fshort-enums Specifying this attribute for @code{struct} and @code{union} types is @@ -3433,9 +3554,29 @@ structure or union members. Specifying the @option{-fshort-enums} flag on the line is equivalent to specifying the @code{packed} attribute on all @code{enum} definitions. -You may only specify this attribute after a closing curly brace on an -@code{enum} definition, not in a @code{typedef} declaration, unless that -declaration also contains the definition of the @code{enum}. +In the following example @code{struct my_packed_struct}'s members are +packed closely together, but the internal layout of its @code{s} member +is not packed -- to do that, @code{struct my_unpacked_struct} would need to +be packed too. + +@smallexample +struct my_unpacked_struct + @{ + char c; + int i; + @}; + +struct my_packed_struct __attribute__ ((__packed__)) + @{ + char c; + int i; + struct my_unpacked_struct s; + @}; +@end smallexample + +You may only specify this attribute on the definition of a @code{enum}, +@code{struct} or @code{union}, not on a @code{typedef} which does not +also define the enumerated type, structure or union. @item transparent_union This attribute, attached to a @code{union} type definition, indicates @@ -3481,19 +3622,19 @@ This interface allows either @code{int *} or @code{union wait *} arguments to be passed, using the @code{int *} calling convention. The program can call @code{wait} with arguments of either type: -@example +@smallexample int w1 () @{ int w; return wait (&w); @} int w2 () @{ union wait w; return wait (&w); @} -@end example +@end smallexample With this interface, @code{wait}'s implementation might look like this: -@example +@smallexample pid_t wait (wait_status_ptr_t p) @{ return waitpid (-1, p.__ip, 0); @} -@end example +@end smallexample @item unused When attached to a type (including a @code{union} or a @code{struct}), @@ -3562,6 +3703,26 @@ If you replaced @code{short_a} with @code{short} in the variable declaration, the above program would abort when compiled with @option{-fstrict-aliasing}, which is on by default at @option{-O2} or above in recent GCC versions. + +@subsection i386 Type Attributes + +Two attributes are currently defined for i386 configurations: +@code{ms_struct} and @code{gcc_struct} + +@item ms_struct +@itemx gcc_struct +@cindex @code{ms_struct} +@cindex @code{gcc_struct} + +If @code{packed} is used on a structure, or if bit-fields are used +it may be that the Microsoft ABI packs them differently +than GCC would normally pack them. Particularly when moving packed +data between functions compiled with GCC and the native Microsoft compiler +(either via function call or as data in a file), it may be necessary to access +either format. + +Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 +compilers to match the native Microsoft compiler. @end table To specify multiple attributes, separate them by commas within the @@ -3593,13 +3754,13 @@ the ISO C99 standard requires. To declare a function inline, use the @code{inline} keyword in its declaration, like this: -@example +@smallexample inline int inc (int *a) @{ (*a)++; @} -@end example +@end smallexample (If you are writing a header file to be included in ISO C programs, write @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.) @@ -3674,10 +3835,10 @@ that will implement the C99 semantics, though it does not do so yet.) GCC does not inline any functions when not optimizing unless you specify the @samp{always_inline} attribute for the function, like this: -@example +@smallexample /* Prototype. */ inline void foo (const char) __attribute__((always_inline)); -@end example +@end smallexample @node Extended Asm @section Assembler Instructions with C Expression Operands @@ -3697,9 +3858,9 @@ each operand. For example, here is how to use the 68881's @code{fsinx} instruction: -@example +@smallexample asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); -@end example +@end smallexample @noindent Here @code{angle} is the C expression for the input operand while @@ -3729,11 +3890,11 @@ assembler code using @code{%[@var{name}]} instead of a percentage sign followed by the operand number. Using named operands the above example could look like: -@example +@smallexample asm ("fsinx %[angle],%[output]" : [output] "=f" (result) : [angle] "f" (angle)); -@end example +@end smallexample @noindent Note that the symbolic operand names have no relation whatsoever to @@ -3757,22 +3918,23 @@ The ordinary output operands must be write-only; GCC will assume that the values in these operands before the instruction are dead and need not be generated. Extended asm supports input-output or read-write operands. Use the constraint character @samp{+} to indicate such an -operand and list it with the output operands. - -When the constraints for the read-write operand (or the operand in which -only some of the bits are to be changed) allows a register, you may, as -an alternative, logically split its function into two separate operands, -one input operand and one write-only output operand. The connection -between them is expressed by constraints which say they need to be in -the same location when the instruction executes. You can use the same C -expression for both operands, or different expressions. For example, -here we write the (fictitious) @samp{combine} instruction with -@code{bar} as its read-only source operand and @code{foo} as its -read-write destination: +operand and list it with the output operands. You should only use +read-write operands when the constraints for the operand (or the +operand in which only some of the bits are to be changed) allow a +register. + +You may, as an alternative, logically split its function into two +separate operands, one input operand and one write-only output +operand. The connection between them is expressed by constraints +which say they need to be in the same location when the instruction +executes. You can use the same C expression for both operands, or +different expressions. For example, here we write the (fictitious) +@samp{combine} instruction with @code{bar} as its read-only source +operand and @code{foo} as its read-write destination: -@example +@smallexample asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); -@end example +@end smallexample @noindent The constraint @samp{"0"} for operand 1 says that it must occupy the @@ -3785,9 +3947,9 @@ of both operands is not enough to guarantee that they will be in the same place in the generated assembler code. The following would not work reliably: -@example +@smallexample asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); -@end example +@end smallexample Various optimizations or reloading could cause operands 0 and 1 to be in different registers; GCC knows no reason not to do so. For example, the @@ -3800,23 +3962,23 @@ code, the result will not work, but GCC can't tell that. As of GCC version 3.1, one may write @code{[@var{name}]} instead of the operand number for a matching constraint. For example: -@example +@smallexample asm ("cmoveq %1,%2,%[result]" : [result] "=r"(result) : "r" (test), "r"(new), "[result]"(old)); -@end example +@end smallexample Some instructions clobber specific hard registers. To describe this, write a third colon after the input operands, followed by the names of the clobbered hard registers (given as strings). Here is a realistic example for the VAX: -@example +@smallexample asm volatile ("movc3 %0,%1,%2" : /* no outputs */ : "g" (from), "g" (to), "g" (count) : "r0", "r1", "r2", "r3", "r4", "r5"); -@end example +@end smallexample You may not write a clobber description in a way that overlaps with an input or output operand. For example, you may not have an operand @@ -3844,13 +4006,35 @@ represents the condition codes as a specific hardware register; condition code is handled differently, and specifying @samp{cc} has no effect. But it is valid no matter what the machine. -If your assembler instruction modifies memory in an unpredictable +If your assembler instructions access memory in an unpredictable fashion, add @samp{memory} to the list of clobbered registers. This -will cause GCC to not keep memory values cached in registers across -the assembler instruction. You will also want to add the -@code{volatile} keyword if the memory affected is not listed in the -inputs or outputs of the @code{asm}, as the @samp{memory} clobber does -not count as a side-effect of the @code{asm}. +will cause GCC to not keep memory values cached in registers across the +assembler instruction and not optimize stores or loads to that memory. +You will also want to add the @code{volatile} keyword if the memory +affected is not listed in the inputs or outputs of the @code{asm}, as +the @samp{memory} clobber does not count as a side-effect of the +@code{asm}. If you know how large the accessed memory is, you can add +it as input or output but if this is not known, you should add +@samp{memory}. As an example, if you access ten bytes of a string, you +can use a memory input like: + +@example +@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}. +@end example + +Note that in the following example the memory input is necessary, +otherwise GCC might optimize the store to @code{x} away: +@example +int foo () +@{ + int x = 42; + int *y = &x; + int result; + asm ("magic stuff accessing an 'int' pointed to by '%1'" + "=&d" (r) : "a" (y), "m" (*y)); + return result; +@} +@end example You can put multiple assembler instructions together in a single @code{asm} template, separated by the characters normally used in assembly @@ -3865,12 +4049,12 @@ read and write the clobbered registers as many times as you like. Here is an example of multiple instructions in a template; it assumes the subroutine @code{_foo} accepts arguments in registers 9 and 10: -@example +@smallexample asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo" : /* no outputs */ : "g" (from), "g" (to) : "r9", "r10"); -@end example +@end smallexample Unless an output operand has the @samp{&} constraint modifier, GCC may allocate it in the same register as an unrelated input operand, on @@ -3883,11 +4067,11 @@ If you want to test the condition code produced by an assembler instruction, you must include a branch and a label in the @code{asm} construct, as follows: -@example +@smallexample asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:" : "g" (result) : "g" (input)); -@end example +@end smallexample @noindent This assumes your assembler supports local labels, as the GNU assembler @@ -3902,12 +4086,12 @@ optimize. Usually the most convenient way to use these @code{asm} instructions is to encapsulate them in macros that look like functions. For example, -@example +@smallexample #define sin(x) \ (@{ double __value, __arg = (x); \ asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ __value; @}) -@end example +@end smallexample @noindent Here the variable @code{__arg} is used to make sure that the instruction @@ -3936,13 +4120,13 @@ You can prevent an @code{asm} instruction from being deleted, moved significantly, or combined, by writing the keyword @code{volatile} after the @code{asm}. For example: -@example +@smallexample #define get_and_set_priority(new) \ (@{ int __old; \ asm volatile ("get_and_set_priority %0, %1" \ : "=g" (__old) : "g" (new)); \ __old; @}) -@end example +@end smallexample @noindent If you write an @code{asm} instruction with no outputs, GCC will know @@ -3956,10 +4140,10 @@ prove that control-flow will never reach the location of the instruction.) In addition, GCC will not reschedule instructions across a volatile @code{asm} instruction. For example: -@example +@smallexample *(volatile int *)addr = foo; asm volatile ("eieio" : : ); -@end example +@end smallexample @noindent Assume @code{addr} contains the address of a memory mapped device @@ -3997,6 +4181,26 @@ If you are writing a header file that should be includable in ISO C programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate Keywords}. +@subsection Size of an @code{asm} + +Some targets require that GCC track the size of each instruction used in +order to generate correct code. Because the final length of an +@code{asm} is only known by the assembler, GCC must make an estimate as +to how big it will be. The estimate is formed by counting the number of +statements in the pattern of the @code{asm} and multiplying that by the +length of the longest instruction on that processor. Statements in the +@code{asm} are identified by newline characters and whatever statement +separator characters are supported by the assembler; on most processors +this is the `@code{;}' character. + +Normally, GCC's estimate is perfectly adequate to ensure that correct +code is generated, but it is possible to confuse the compiler if you use +pseudo instructions or assembler macros that expand into multiple real +instructions or if you use assembler directives that expand to more +space in the object file than would be needed for a single instruction. +If this happens then the assembler will produce a diagnostic saying that +a label is unreachable. + @subsection i386 floating point asm operands There are several rules on the usage of stack-like regs in @@ -4027,9 +4231,9 @@ the reg-stack than any input that is not implicitly popped. It is possible that if an input dies in an insn, reload might use the input reg for an output reload. Consider this example: -@example +@smallexample asm ("foo" : "=t" (a) : "f" (b)); -@end example +@end smallexample This asm says that input B is not popped by the asm, and that the asm pushes a result onto the reg-stack, i.e., the stack is one @@ -4042,9 +4246,9 @@ constraints must use the @code{&} earlyclobber. The asm above would be written as -@example +@smallexample asm ("foo" : "=&t" (a) : "f" (b)); -@end example +@end smallexample @item Some operands need to be in particular places on the stack. All @@ -4075,17 +4279,17 @@ unrelated to the inputs and outputs. Here are a couple of reasonable asms to want to write. This asm takes one input, which is internally popped, and produces two outputs. -@example +@smallexample asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); -@end example +@end smallexample This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode, and replaces them with one output. The user must code the @code{st(1)} clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs. -@example +@smallexample asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); -@end example +@end smallexample @include md.texi @@ -4099,9 +4303,9 @@ You can specify the name to be used in the assembler code for a C function or variable by writing the @code{asm} (or @code{__asm__}) keyword after the declarator as follows: -@example +@smallexample int foo asm ("myfoo") = 2; -@end example +@end smallexample @noindent This specifies that the name to be used for the variable @code{foo} in @@ -4123,13 +4327,13 @@ You cannot use @code{asm} in this way in a function @emph{definition}; but you can get the same effect by writing a declaration for the function before its definition and putting @code{asm} there, like this: -@example +@smallexample extern func () asm ("FUNC"); func (x, y) int x, y; /* @r{@dots{}} */ -@end example +@end smallexample It is up to you to make sure that the assembler names you choose do not conflict with any other assembler symbols. Also, you must not use a @@ -4182,9 +4386,9 @@ specified for that operand in the @code{asm}.) You can define a global register variable in GNU C like this: -@example +@smallexample register int *foo asm ("a5"); -@end example +@end smallexample @noindent Here @code{a5} is the name of the register which should be used. Choose a @@ -4281,9 +4485,9 @@ Of course, it will not do to use more than a few of those. You can define a local register variable with a specified register like this: -@example +@smallexample register int *foo asm ("a5"); -@end example +@end smallexample @noindent Here @code{a5} is the name of the register which should be used. Note @@ -4340,11 +4544,11 @@ Other C compilers won't accept these alternative keywords; if you want to compile with another compiler, you can define the alternate keywords as macros to replace them with the customary keywords. It looks like this: -@example +@smallexample #ifndef __GNUC__ #define __asm__ asm #endif -@end example +@end smallexample @findex __extension__ @opindex pedantic @@ -4373,18 +4577,47 @@ This extension is not supported by GNU C++. @node Function Names @section Function Names as Strings +@cindex @code{__func__} identifier @cindex @code{__FUNCTION__} identifier @cindex @code{__PRETTY_FUNCTION__} identifier -@cindex @code{__func__} identifier -GCC predefines two magic identifiers to hold the name of the current -function. The identifier @code{__FUNCTION__} holds the name of the function -as it appears in the source. The identifier @code{__PRETTY_FUNCTION__} -holds the name of the function pretty printed in a language specific -fashion. +GCC provides three magic variables which hold the name of the current +function, as a string. The first of these is @code{__func__}, which +is part of the C99 standard: + +@display +The identifier @code{__func__} is implicitly declared by the translator +as if, immediately following the opening brace of each function +definition, the declaration + +@smallexample +static const char __func__[] = "function-name"; +@end smallexample + +appeared, where function-name is the name of the lexically-enclosing +function. This name is the unadorned name of the function. +@end display -These names are always the same in a C function, but in a C++ function -they may be different. For example, this program: +@code{__FUNCTION__} is another name for @code{__func__}. Older +versions of GCC recognize only this name. However, it is not +standardized. For maximum portability, we recommend you use +@code{__func__}, but provide a fallback definition with the +preprocessor: + +@smallexample +#if __STDC_VERSION__ < 199901L +# if __GNUC__ >= 2 +# define __func__ __FUNCTION__ +# else +# define __func__ "<unknown>" +# endif +#endif +@end smallexample + +In C, @code{__PRETTY_FUNCTION__} is yet another name for +@code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains +the type signature of the function as well as its bare name. For +example, this program: @smallexample extern "C" @{ @@ -4393,7 +4626,7 @@ extern int printf (char *, ...); class a @{ public: - sub (int i) + void sub (int i) @{ printf ("__FUNCTION__ = %s\n", __FUNCTION__); printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); @@ -4414,46 +4647,16 @@ gives this output: @smallexample __FUNCTION__ = sub -__PRETTY_FUNCTION__ = int a::sub (int) +__PRETTY_FUNCTION__ = void a::sub(int) @end smallexample -The compiler automagically replaces the identifiers with a string -literal containing the appropriate name. Thus, they are neither -preprocessor macros, like @code{__FILE__} and @code{__LINE__}, nor -variables. This means that they catenate with other string literals, and -that they can be used to initialize char arrays. For example - -@smallexample -char here[] = "Function " __FUNCTION__ " in " __FILE__; -@end smallexample - -On the other hand, @samp{#ifdef __FUNCTION__} does not have any special -meaning inside a function, since the preprocessor does not do anything -special with the identifier @code{__FUNCTION__}. - -Note that these semantics are deprecated, and that GCC 3.2 will handle -@code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} the same way as -@code{__func__}. @code{__func__} is defined by the ISO standard C99: - -@display -The identifier @code{__func__} is implicitly declared by the translator -as if, immediately following the opening brace of each function -definition, the declaration - -@smallexample -static const char __func__[] = "function-name"; -@end smallexample - -appeared, where function-name is the name of the lexically-enclosing -function. This name is the unadorned name of the function. -@end display - -By this definition, @code{__func__} is a variable, not a string literal. -In particular, @code{__func__} does not catenate with other string -literals. - -In @code{C++}, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} are -variables, declared in the same way as @code{__func__}. +These identifiers are not preprocessor macros. In GCC 3.3 and +earlier, in C only, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} +were treated as string literals; they could be used to initialize +@code{char} arrays, and they could be concatenated with other string +literals. GCC 3.4 and later treat them as variables, like +@code{__func__}. In C++, @code{__FUNCTION__} and +@code{__PRETTY_FUNCTION__} have always been variables. @node Return Address @section Getting the Return or Frame Address of a Function @@ -4519,9 +4722,9 @@ this way. The first step in using these extensions is to provide the necessary data types. This should be done using an appropriate @code{typedef}: -@example +@smallexample typedef int v4si __attribute__ ((mode(V4SI))); -@end example +@end smallexample The base type @code{int} is effectively ignored by the compiler, the actual properties of the new type @code{v4si} are defined by the @@ -4546,14 +4749,14 @@ A floating point value, as wide as a DI mode integer, usually 64 bits. @end table Specifying a combination that is not valid for the current architecture -will cause gcc to synthesize the instructions using a narrower mode. +will cause GCC to synthesize the instructions using a narrower mode. For example, if you specify a variable of type @code{V4SI} and your -architecture does not allow for this specific SIMD type, gcc will +architecture does not allow for this specific SIMD type, GCC will produce code that uses 4 @code{SIs}. The types defined in this manner can be used with a subset of normal C -operations. Currently, gcc will allow using the following operators on -these types: @code{+, -, *, /, unary minus}@. +operations. Currently, GCC will allow using the following operators +on these types: @code{+, -, *, /, unary minus, ^, |, &, ~}@. The operations behave like C++ @code{valarrays}. Addition is defined as the addition of the corresponding elements of the operands. For @@ -4561,17 +4764,18 @@ example, in the code below, each of the 4 elements in @var{a} will be added to the corresponding 4 elements in @var{b} and the resulting vector will be stored in @var{c}. -@example +@smallexample typedef int v4si __attribute__ ((mode(V4SI))); v4si a, b, c; c = a + b; -@end example +@end smallexample -Subtraction, multiplication, and division operate in a similar manner. -Likewise, the result of using the unary minus operator on a vector type -is a vector whose elements are the negative value of the corresponding +Subtraction, multiplication, division, and the logical operations +operate in a similar manner. Likewise, the result of using the unary +minus or complement operators on a vector type is a vector whose +elements are the negative or complemented values of the corresponding elements in the operand. You can declare variables and use them in function calls and returns, as @@ -4589,14 +4793,14 @@ of built-in functions that can be used to operate on vectors. For example, a function to add two vectors and multiply the result by a third could look like this: -@example +@smallexample v4si f (v4si a, v4si b, v4si c) @{ v4si tmp = __builtin_addv4si (a, b); return __builtin_mulv4si (tmp, c); @} -@end example +@end smallexample @node Other Builtins @section Other built-in functions provided by GCC @@ -4607,55 +4811,283 @@ v4si f (v4si a, v4si b, v4si c) @findex __builtin_islessequal @findex __builtin_islessgreater @findex __builtin_isunordered +@findex _Exit +@findex _exit @findex abort @findex abs +@findex acos +@findex acosf +@findex acosh +@findex acoshf +@findex acoshl +@findex acosl @findex alloca +@findex asin +@findex asinf +@findex asinh +@findex asinhf +@findex asinhl +@findex asinl +@findex atan +@findex atan2 +@findex atan2f +@findex atan2l +@findex atanf +@findex atanh +@findex atanhf +@findex atanhl +@findex atanl @findex bcmp @findex bzero +@findex cabs +@findex cabsf +@findex cabsl +@findex cacos +@findex cacosf +@findex cacosh +@findex cacoshf +@findex cacoshl +@findex cacosl +@findex calloc +@findex carg +@findex cargf +@findex cargl +@findex casin +@findex casinf +@findex casinh +@findex casinhf +@findex casinhl +@findex casinl +@findex catan +@findex catanf +@findex catanh +@findex catanhf +@findex catanhl +@findex catanl +@findex cbrt +@findex cbrtf +@findex cbrtl +@findex ccos +@findex ccosf +@findex ccosh +@findex ccoshf +@findex ccoshl +@findex ccosl +@findex ceil +@findex ceilf +@findex ceill +@findex cexp +@findex cexpf +@findex cexpl @findex cimag @findex cimagf @findex cimagl @findex conj @findex conjf @findex conjl +@findex copysign +@findex copysignf +@findex copysignl @findex cos @findex cosf +@findex cosh +@findex coshf +@findex coshl @findex cosl +@findex cpow +@findex cpowf +@findex cpowl +@findex cproj +@findex cprojf +@findex cprojl @findex creal @findex crealf @findex creall +@findex csin +@findex csinf +@findex csinh +@findex csinhf +@findex csinhl +@findex csinl +@findex csqrt +@findex csqrtf +@findex csqrtl +@findex ctan +@findex ctanf +@findex ctanh +@findex ctanhf +@findex ctanhl +@findex ctanl +@findex dcgettext +@findex dgettext +@findex drem +@findex dremf +@findex dreml +@findex erf +@findex erfc +@findex erfcf +@findex erfcl +@findex erff +@findex erfl @findex exit -@findex _exit -@findex _Exit @findex exp +@findex exp10 +@findex exp10f +@findex exp10l +@findex exp2 +@findex exp2f +@findex exp2l @findex expf @findex expl +@findex expm1 +@findex expm1f +@findex expm1l @findex fabs @findex fabsf @findex fabsl +@findex fdim +@findex fdimf +@findex fdiml @findex ffs +@findex floor +@findex floorf +@findex floorl +@findex fma +@findex fmaf +@findex fmal +@findex fmax +@findex fmaxf +@findex fmaxl +@findex fmin +@findex fminf +@findex fminl +@findex fmod +@findex fmodf +@findex fmodl @findex fprintf @findex fprintf_unlocked @findex fputs @findex fputs_unlocked +@findex frexp +@findex frexpf +@findex frexpl +@findex fscanf +@findex gamma +@findex gammaf +@findex gammal +@findex gettext +@findex hypot +@findex hypotf +@findex hypotl +@findex ilogb +@findex ilogbf +@findex ilogbl @findex imaxabs @findex index +@findex j0 +@findex j0f +@findex j0l +@findex j1 +@findex j1f +@findex j1l +@findex jn +@findex jnf +@findex jnl @findex labs +@findex ldexp +@findex ldexpf +@findex ldexpl +@findex lgamma +@findex lgammaf +@findex lgammal @findex llabs +@findex llrint +@findex llrintf +@findex llrintl +@findex llround +@findex llroundf +@findex llroundl @findex log +@findex log10 +@findex log10f +@findex log10l +@findex log1p +@findex log1pf +@findex log1pl +@findex log2 +@findex log2f +@findex log2l +@findex logb +@findex logbf +@findex logbl @findex logf @findex logl +@findex lrint +@findex lrintf +@findex lrintl +@findex lround +@findex lroundf +@findex lroundl +@findex malloc @findex memcmp @findex memcpy +@findex mempcpy @findex memset +@findex modf +@findex modff +@findex modfl +@findex nearbyint +@findex nearbyintf +@findex nearbyintl +@findex nextafter +@findex nextafterf +@findex nextafterl +@findex nexttoward +@findex nexttowardf +@findex nexttowardl +@findex pow +@findex pow10 +@findex pow10f +@findex pow10l +@findex powf +@findex powl @findex printf @findex printf_unlocked @findex putchar @findex puts +@findex remainder +@findex remainderf +@findex remainderl +@findex remquo +@findex remquof +@findex remquol @findex rindex -@findex scanf +@findex rint +@findex rintf +@findex rintl +@findex round +@findex roundf +@findex roundl +@findex scalb +@findex scalbf +@findex scalbl +@findex scalbln +@findex scalblnf +@findex scalblnf +@findex scalbn +@findex scalbnf +@findex scanfnl +@findex significand +@findex significandf +@findex significandl @findex sin +@findex sincos +@findex sincosf +@findex sincosl @findex sinf +@findex sinh +@findex sinhf +@findex sinhl @findex sinl @findex snprintf @findex sprintf @@ -4663,11 +5095,15 @@ v4si f (v4si a, v4si b, v4si c) @findex sqrtf @findex sqrtl @findex sscanf +@findex stpcpy @findex strcat @findex strchr @findex strcmp @findex strcpy @findex strcspn +@findex strdup +@findex strfmon +@findex strftime @findex strlen @findex strncat @findex strncmp @@ -4676,11 +5112,34 @@ v4si f (v4si a, v4si b, v4si c) @findex strrchr @findex strspn @findex strstr +@findex tan +@findex tanf +@findex tanh +@findex tanhf +@findex tanhl +@findex tanl +@findex tgamma +@findex tgammaf +@findex tgammal +@findex trunc +@findex truncf +@findex truncl +@findex vfprintf +@findex vfscanf @findex vprintf @findex vscanf @findex vsnprintf @findex vsprintf @findex vsscanf +@findex y0 +@findex y0f +@findex y0l +@findex y1 +@findex y1f +@findex y1l +@findex yn +@findex ynf +@findex ynl GCC provides a large number of built-in functions other than the ones mentioned above. Some of these are for internal use in the processing @@ -4701,47 +5160,102 @@ be emitted. @opindex ansi @opindex std -The functions @code{abort}, @code{exit}, @code{_Exit} and @code{_exit} -are recognized and presumed not to return, but otherwise are not built -in. @code{_exit} is not recognized in strict ISO C mode (@option{-ansi}, -@option{-std=c89} or @option{-std=c99}). @code{_Exit} is not recognized in -strict C89 mode (@option{-ansi} or @option{-std=c89}). All these functions -have corresponding versions prefixed with @code{__builtin_}, which may be -used even in strict C89 mode. - -Outside strict ISO C mode, the functions @code{alloca}, @code{bcmp}, -@code{bzero}, @code{index}, @code{rindex}, @code{ffs}, @code{fputs_unlocked}, -@code{printf_unlocked} and @code{fprintf_unlocked} may be handled as -built-in functions. All these functions have corresponding versions +Outside strict ISO C mode (@option{-ansi}, @option{-std=c89} or +@option{-std=c99}), the functions +@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, +@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, +@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, +@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, @code{fputs_unlocked}, +@code{gammaf}, @code{gammal}, @code{gamma}, @code{gettext}, +@code{index}, @code{j0f}, @code{j0l}, @code{j0}, @code{j1f}, @code{j1l}, +@code{j1}, @code{jnf}, @code{jnl}, @code{jn}, @code{mempcpy}, +@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, +@code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb}, +@code{significandf}, @code{significandl}, @code{significand}, +@code{sincosf}, @code{sincosl}, @code{sincos}, @code{stpcpy}, +@code{strdup}, @code{strfmon}, @code{y0f}, @code{y0l}, @code{y0}, +@code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and @code{yn} +may be handled as built-in functions. +All these functions have corresponding versions prefixed with @code{__builtin_}, which may be used even in strict C89 mode. -The ISO C99 functions @code{conj}, @code{conjf}, @code{conjl}, -@code{creal}, @code{crealf}, @code{creall}, @code{cimag}, @code{cimagf}, -@code{cimagl}, @code{imaxabs}, @code{llabs}, @code{snprintf}, -@code{vscanf}, @code{vsnprintf} and @code{vsscanf} are handled as built-in -functions except in strict ISO C90 mode. There are also built-in -versions of the ISO C99 functions @code{cosf}, @code{cosl}, -@code{expf}, @code{expl}, @code{fabsf}, @code{fabsl}, -@code{logf}, @code{logl}, @code{sinf}, @code{sinl}, @code{sqrtf}, and -@code{sqrtl}, that are recognized in any mode since ISO C90 reserves -these names for the purpose to which ISO C99 puts them. All these -functions have corresponding versions prefixed with @code{__builtin_}. - -The ISO C90 functions @code{abs}, @code{cos}, @code{exp}, @code{fabs}, -@code{fprintf}, @code{fputs}, @code{labs}, @code{log}, -@code{memcmp}, @code{memcpy}, -@code{memset}, @code{printf}, @code{putchar}, @code{puts}, @code{scanf}, -@code{sin}, @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, -@code{strcat}, -@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, -@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, -@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, -@code{vprintf} and @code{vsprintf} are all -recognized as built-in functions unless @option{-fno-builtin} is -specified (or @option{-fno-builtin-@var{function}} is specified for an -individual function). All of these functions have corresponding -versions prefixed with @code{__builtin_}. +The ISO C99 functions +@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, +@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, +@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, +@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, +@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, +@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, +@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, +@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, +@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, +@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, +@code{cimagl}, @code{cimag}, +@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, +@code{copysignl}, @code{copysign}, @code{cpowf}, @code{cpowl}, +@code{cpow}, @code{cprojf}, @code{cprojl}, @code{cproj}, @code{crealf}, +@code{creall}, @code{creal}, @code{csinf}, @code{csinhf}, @code{csinhl}, +@code{csinh}, @code{csinl}, @code{csin}, @code{csqrtf}, @code{csqrtl}, +@code{csqrt}, @code{ctanf}, @code{ctanhf}, @code{ctanhl}, @code{ctanh}, +@code{ctanl}, @code{ctan}, @code{erfcf}, @code{erfcl}, @code{erfc}, +@code{erff}, @code{erfl}, @code{erf}, @code{exp2f}, @code{exp2l}, +@code{exp2}, @code{expm1f}, @code{expm1l}, @code{expm1}, @code{fdimf}, +@code{fdiml}, @code{fdim}, @code{fmaf}, @code{fmal}, @code{fmaxf}, +@code{fmaxl}, @code{fmax}, @code{fma}, @code{fminf}, @code{fminl}, +@code{fmin}, @code{hypotf}, @code{hypotl}, @code{hypot}, @code{ilogbf}, +@code{ilogbl}, @code{ilogb}, @code{imaxabs}, @code{lgammaf}, +@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, +@code{llrintl}, @code{llrint}, @code{llroundf}, @code{llroundl}, +@code{llround}, @code{log1pf}, @code{log1pl}, @code{log1p}, +@code{log2f}, @code{log2l}, @code{log2}, @code{logbf}, @code{logbl}, +@code{logb}, @code{lrintf}, @code{lrintl}, @code{lrint}, @code{lroundf}, +@code{lroundl}, @code{lround}, @code{nearbyintf}, @code{nearbyintl}, +@code{nearbyint}, @code{nextafterf}, @code{nextafterl}, +@code{nextafter}, @code{nexttowardf}, @code{nexttowardl}, +@code{nexttoward}, @code{remainderf}, @code{remainderl}, +@code{remainder}, @code{remquof}, @code{remquol}, @code{remquo}, +@code{rintf}, @code{rintl}, @code{rint}, @code{roundf}, @code{roundl}, +@code{round}, @code{scalblnf}, @code{scalblnl}, @code{scalbln}, +@code{scalbnf}, @code{scalbnl}, @code{scalbn}, @code{snprintf}, +@code{tgammaf}, @code{tgammal}, @code{tgamma}, @code{truncf}, +@code{truncl}, @code{trunc}, @code{vfscanf}, @code{vscanf}, +@code{vsnprintf} and @code{vsscanf} +are handled as built-in functions +except in strict ISO C90 mode (@option{-ansi} or @option{-std=c89}). + +There are also built-in versions of the ISO C99 functions +@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, +@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, +@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, +@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, +@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, +@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, +@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, +@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, +@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} +that are recognized in any mode since ISO C90 reserves these names for +the purpose to which ISO C99 puts them. All these functions have +corresponding versions prefixed with @code{__builtin_}. + +The ISO C90 functions +@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, +@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, +@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, +@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, @code{labs}, +@code{ldexp}, @code{log10}, @code{log}, @code{malloc}, @code{memcmp}, +@code{memcpy}, @code{memset}, @code{modf}, @code{pow}, @code{printf}, +@code{putchar}, @code{puts}, @code{scanf}, @code{sinh}, @code{sin}, +@code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, +@code{strcat}, @code{strchr}, @code{strcmp}, @code{strcpy}, +@code{strcspn}, @code{strlen}, @code{strncat}, @code{strncmp}, +@code{strncpy}, @code{strpbrk}, @code{strrchr}, @code{strspn}, +@code{strstr}, @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} +and @code{vsprintf} +are all recognized as built-in functions unless +@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} +is specified for an individual function). All of these functions have +corresponding versions prefixed with @code{__builtin_}. GCC provides built-in versions of the ISO C99 floating point comparison macros that avoid raising exceptions for unordered operands. They have @@ -4773,8 +5287,10 @@ similarity. Consequently, @code{short *} is not similar to @code{short **}. Furthermore, two types that are typedefed are considered compatible if their underlying types are compatible. -An @code{enum} type is considered to be compatible with another -@code{enum} type. For example, @code{enum @{foo, bar@}} is similar to +An @code{enum} type is not considered to be compatible with another +@code{enum} type even if both are compatible with the same integer +type; this is what the C standard specifies. +For example, @code{enum @{foo, bar@}} is not similar to @code{enum @{hot, dog@}}. You would typically use this function in code whose execution varies @@ -5007,7 +5523,7 @@ do not implement, a description of the parsing is in order. The string is parsed as by @code{strtol}; that is, the base is recognized by leading @samp{0} or @samp{0x} prefixes. The number parsed is placed in the significand such that the least significant bit of the number -is at the least significant bit of the significand. The number is +is at the least significant bit of the significand. The number is truncated to fit the significand field provided. The significand is forced to be a quiet NaN. @@ -5024,9 +5540,9 @@ Similar to @code{__builtin_nan}, except the return type is @code{long double}. @end deftypefn @deftypefn {Built-in Function} double __builtin_nans (const char *str) -Similar to @code{__builtin_nan}, except the significand is forced +Similar to @code{__builtin_nan}, except the significand is forced to be a signaling NaN. The @code{nans} function is proposed by -@uref{http://std.dkuug.dk/JTC1/SC22/WG14/www/docs/n965.htm,,WG14 N965}. +@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. @end deftypefn @deftypefn {Built-in Function} float __builtin_nansf (const char *str) @@ -5037,6 +5553,81 @@ Similar to @code{__builtin_nans}, except the return type is @code{float}. Similar to @code{__builtin_nans}, except the return type is @code{long double}. @end deftypefn +@deftypefn {Built-in Function} int __builtin_ffs (unsigned int x) +Returns one plus the index of the least significant 1-bit of @var{x}, or +if @var{x} is zero, returns zero. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) +Returns the number of leading 0-bits in @var{x}, starting at the most +significant bit position. If @var{x} is 0, the result is undefined. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) +Returns the number of trailing 0-bits in @var{x}, starting at the least +significant bit position. If @var{x} is 0, the result is undefined. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) +Returns the number of 1-bits in @var{x}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) +Returns the parity of @var{x}, i.@:e. the number of 1-bits in @var{x} +modulo 2. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ffsl (unsigned long) +Similar to @code{__builtin_ffs}, except the argument type is +@code{unsigned long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) +Similar to @code{__builtin_clz}, except the argument type is +@code{unsigned long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) +Similar to @code{__builtin_ctz}, except the argument type is +@code{unsigned long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) +Similar to @code{__builtin_popcount}, except the argument type is +@code{unsigned long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) +Similar to @code{__builtin_parity}, except the argument type is +@code{unsigned long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ffsll (unsigned long long) +Similar to @code{__builtin_ffs}, except the argument type is +@code{unsigned long long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) +Similar to @code{__builtin_clz}, except the argument type is +@code{unsigned long long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) +Similar to @code{__builtin_ctz}, except the argument type is +@code{unsigned long long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) +Similar to @code{__builtin_popcount}, except the argument type is +@code{unsigned long long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) +Similar to @code{__builtin_parity}, except the argument type is +@code{unsigned long long}. +@end deftypefn + + @node Target Builtins @section Built-in Functions Specific to Particular Target Machines @@ -5046,6 +5637,7 @@ instructions, but allow the compiler to schedule those calls. @menu * Alpha Built-in Functions:: +* ARM Built-in Functions:: * X86 Built-in Functions:: * PowerPC AltiVec Built-in Functions:: @end menu @@ -5059,7 +5651,7 @@ processors, depending on the command-line switches used. The following built-in functions are always available. They all generate the machine instruction that is part of the name. -@example +@smallexample long __builtin_alpha_implver (void) long __builtin_alpha_rpcc (void) long __builtin_alpha_amask (long) @@ -5088,14 +5680,14 @@ long __builtin_alpha_mskqh (long, long) long __builtin_alpha_umulh (long, long) long __builtin_alpha_zap (long, long) long __builtin_alpha_zapnot (long, long) -@end example +@end smallexample The following built-in functions are always with @option{-mmax} or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or later. They all generate the machine instruction that is part of the name. -@example +@smallexample long __builtin_alpha_pklb (long) long __builtin_alpha_pkwb (long) long __builtin_alpha_unpkbl (long) @@ -5109,28 +5701,175 @@ long __builtin_alpha_maxsb8 (long, long) long __builtin_alpha_maxuw4 (long, long) long __builtin_alpha_maxsw4 (long, long) long __builtin_alpha_perr (long, long) -@end example +@end smallexample The following built-in functions are always with @option{-mcix} or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or later. They all generate the machine instruction that is part of the name. -@example +@smallexample long __builtin_alpha_cttz (long) long __builtin_alpha_ctlz (long) long __builtin_alpha_ctpop (long) -@end example +@end smallexample The following builtins are available on systems that use the OSF/1 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} PAL calls, but when invoked with @option{-mtls-kernel}, they invoke @code{rdval} and @code{wrval}. -@example +@smallexample void *__builtin_thread_pointer (void) void __builtin_set_thread_pointer (void *) -@end example +@end smallexample + +@node ARM Built-in Functions +@subsection ARM Built-in Functions + +These built-in functions are available for the ARM family of +processors, when the @option{-mcpu=iwmmxt} switch is used: + +@smallexample +typedef int v2si __attribute__ ((vector_size (8))); +typedef short v4hi __attribute__ ((vector_size (8))); +typedef char v8qi __attribute__ ((vector_size (8))); + +int __builtin_arm_getwcx (int) +void __builtin_arm_setwcx (int, int) +int __builtin_arm_textrmsb (v8qi, int) +int __builtin_arm_textrmsh (v4hi, int) +int __builtin_arm_textrmsw (v2si, int) +int __builtin_arm_textrmub (v8qi, int) +int __builtin_arm_textrmuh (v4hi, int) +int __builtin_arm_textrmuw (v2si, int) +v8qi __builtin_arm_tinsrb (v8qi, int) +v4hi __builtin_arm_tinsrh (v4hi, int) +v2si __builtin_arm_tinsrw (v2si, int) +long long __builtin_arm_tmia (long long, int, int) +long long __builtin_arm_tmiabb (long long, int, int) +long long __builtin_arm_tmiabt (long long, int, int) +long long __builtin_arm_tmiaph (long long, int, int) +long long __builtin_arm_tmiatb (long long, int, int) +long long __builtin_arm_tmiatt (long long, int, int) +int __builtin_arm_tmovmskb (v8qi) +int __builtin_arm_tmovmskh (v4hi) +int __builtin_arm_tmovmskw (v2si) +long long __builtin_arm_waccb (v8qi) +long long __builtin_arm_wacch (v4hi) +long long __builtin_arm_waccw (v2si) +v8qi __builtin_arm_waddb (v8qi, v8qi) +v8qi __builtin_arm_waddbss (v8qi, v8qi) +v8qi __builtin_arm_waddbus (v8qi, v8qi) +v4hi __builtin_arm_waddh (v4hi, v4hi) +v4hi __builtin_arm_waddhss (v4hi, v4hi) +v4hi __builtin_arm_waddhus (v4hi, v4hi) +v2si __builtin_arm_waddw (v2si, v2si) +v2si __builtin_arm_waddwss (v2si, v2si) +v2si __builtin_arm_waddwus (v2si, v2si) +v8qi __builtin_arm_walign (v8qi, v8qi, int) +long long __builtin_arm_wand(long long, long long) +long long __builtin_arm_wandn (long long, long long) +v8qi __builtin_arm_wavg2b (v8qi, v8qi) +v8qi __builtin_arm_wavg2br (v8qi, v8qi) +v4hi __builtin_arm_wavg2h (v4hi, v4hi) +v4hi __builtin_arm_wavg2hr (v4hi, v4hi) +v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) +v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) +v2si __builtin_arm_wcmpeqw (v2si, v2si) +v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) +v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) +v2si __builtin_arm_wcmpgtsw (v2si, v2si) +v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) +v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) +v2si __builtin_arm_wcmpgtuw (v2si, v2si) +long long __builtin_arm_wmacs (long long, v4hi, v4hi) +long long __builtin_arm_wmacsz (v4hi, v4hi) +long long __builtin_arm_wmacu (long long, v4hi, v4hi) +long long __builtin_arm_wmacuz (v4hi, v4hi) +v4hi __builtin_arm_wmadds (v4hi, v4hi) +v4hi __builtin_arm_wmaddu (v4hi, v4hi) +v8qi __builtin_arm_wmaxsb (v8qi, v8qi) +v4hi __builtin_arm_wmaxsh (v4hi, v4hi) +v2si __builtin_arm_wmaxsw (v2si, v2si) +v8qi __builtin_arm_wmaxub (v8qi, v8qi) +v4hi __builtin_arm_wmaxuh (v4hi, v4hi) +v2si __builtin_arm_wmaxuw (v2si, v2si) +v8qi __builtin_arm_wminsb (v8qi, v8qi) +v4hi __builtin_arm_wminsh (v4hi, v4hi) +v2si __builtin_arm_wminsw (v2si, v2si) +v8qi __builtin_arm_wminub (v8qi, v8qi) +v4hi __builtin_arm_wminuh (v4hi, v4hi) +v2si __builtin_arm_wminuw (v2si, v2si) +v4hi __builtin_arm_wmulsm (v4hi, v4hi) +v4hi __builtin_arm_wmulul (v4hi, v4hi) +v4hi __builtin_arm_wmulum (v4hi, v4hi) +long long __builtin_arm_wor (long long, long long) +v2si __builtin_arm_wpackdss (long long, long long) +v2si __builtin_arm_wpackdus (long long, long long) +v8qi __builtin_arm_wpackhss (v4hi, v4hi) +v8qi __builtin_arm_wpackhus (v4hi, v4hi) +v4hi __builtin_arm_wpackwss (v2si, v2si) +v4hi __builtin_arm_wpackwus (v2si, v2si) +long long __builtin_arm_wrord (long long, long long) +long long __builtin_arm_wrordi (long long, int) +v4hi __builtin_arm_wrorh (v4hi, long long) +v4hi __builtin_arm_wrorhi (v4hi, int) +v2si __builtin_arm_wrorw (v2si, long long) +v2si __builtin_arm_wrorwi (v2si, int) +v2si __builtin_arm_wsadb (v8qi, v8qi) +v2si __builtin_arm_wsadbz (v8qi, v8qi) +v2si __builtin_arm_wsadh (v4hi, v4hi) +v2si __builtin_arm_wsadhz (v4hi, v4hi) +v4hi __builtin_arm_wshufh (v4hi, int) +long long __builtin_arm_wslld (long long, long long) +long long __builtin_arm_wslldi (long long, int) +v4hi __builtin_arm_wsllh (v4hi, long long) +v4hi __builtin_arm_wsllhi (v4hi, int) +v2si __builtin_arm_wsllw (v2si, long long) +v2si __builtin_arm_wsllwi (v2si, int) +long long __builtin_arm_wsrad (long long, long long) +long long __builtin_arm_wsradi (long long, int) +v4hi __builtin_arm_wsrah (v4hi, long long) +v4hi __builtin_arm_wsrahi (v4hi, int) +v2si __builtin_arm_wsraw (v2si, long long) +v2si __builtin_arm_wsrawi (v2si, int) +long long __builtin_arm_wsrld (long long, long long) +long long __builtin_arm_wsrldi (long long, int) +v4hi __builtin_arm_wsrlh (v4hi, long long) +v4hi __builtin_arm_wsrlhi (v4hi, int) +v2si __builtin_arm_wsrlw (v2si, long long) +v2si __builtin_arm_wsrlwi (v2si, int) +v8qi __builtin_arm_wsubb (v8qi, v8qi) +v8qi __builtin_arm_wsubbss (v8qi, v8qi) +v8qi __builtin_arm_wsubbus (v8qi, v8qi) +v4hi __builtin_arm_wsubh (v4hi, v4hi) +v4hi __builtin_arm_wsubhss (v4hi, v4hi) +v4hi __builtin_arm_wsubhus (v4hi, v4hi) +v2si __builtin_arm_wsubw (v2si, v2si) +v2si __builtin_arm_wsubwss (v2si, v2si) +v2si __builtin_arm_wsubwus (v2si, v2si) +v4hi __builtin_arm_wunpckehsb (v8qi) +v2si __builtin_arm_wunpckehsh (v4hi) +long long __builtin_arm_wunpckehsw (v2si) +v4hi __builtin_arm_wunpckehub (v8qi) +v2si __builtin_arm_wunpckehuh (v4hi) +long long __builtin_arm_wunpckehuw (v2si) +v4hi __builtin_arm_wunpckelsb (v8qi) +v2si __builtin_arm_wunpckelsh (v4hi) +long long __builtin_arm_wunpckelsw (v2si) +v4hi __builtin_arm_wunpckelub (v8qi) +v2si __builtin_arm_wunpckeluh (v4hi) +long long __builtin_arm_wunpckeluw (v2si) +v8qi __builtin_arm_wunpckihb (v8qi, v8qi) +v4hi __builtin_arm_wunpckihh (v4hi, v4hi) +v2si __builtin_arm_wunpckihw (v2si, v2si) +v8qi __builtin_arm_wunpckilb (v8qi, v8qi) +v4hi __builtin_arm_wunpckilh (v4hi, v4hi) +v2si __builtin_arm_wunpckilw (v2si, v2si) +long long __builtin_arm_wxor (long long, long long) +long long __builtin_arm_wzero () +@end smallexample @node X86 Built-in Functions @subsection X86 Built-in Functions @@ -5156,7 +5895,7 @@ entire vector register, interpreting it as a 128-bit integer, these use mode The following built-in functions are made available by @option{-mmmx}. All of them generate the machine instruction that is part of the name. -@example +@smallexample v8qi __builtin_ia32_paddb (v8qi, v8qi) v4hi __builtin_ia32_paddw (v4hi, v4hi) v2si __builtin_ia32_paddd (v2si, v2si) @@ -5192,14 +5931,14 @@ v2si __builtin_ia32_punpckldq (v2si, v2si) v8qi __builtin_ia32_packsswb (v4hi, v4hi) v4hi __builtin_ia32_packssdw (v2si, v2si) v8qi __builtin_ia32_packuswb (v4hi, v4hi) -@end example +@end smallexample The following built-in functions are made available either with @option{-msse}, or with a combination of @option{-m3dnow} and @option{-march=athlon}. All of them generate the machine instruction that is part of the name. -@example +@smallexample v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) v8qi __builtin_ia32_pavgb (v8qi, v8qi) v4hi __builtin_ia32_pavgw (v4hi, v4hi) @@ -5214,12 +5953,12 @@ int __builtin_ia32_pmovmskb (v8qi) void __builtin_ia32_maskmovq (v8qi, v8qi, char *) void __builtin_ia32_movntq (di *, di) void __builtin_ia32_sfence (void) -@end example +@end smallexample The following built-in functions are available when @option{-msse} is used. All of them generate the machine instruction that is part of the name. -@example +@smallexample int __builtin_ia32_comieq (v4sf, v4sf) int __builtin_ia32_comineq (v4sf, v4sf) int __builtin_ia32_comilt (v4sf, v4sf) @@ -5288,7 +6027,7 @@ v4sf __builtin_ia32_sqrtss (v4sf) v4sf __builtin_ia32_shufps (v4sf, v4sf, int) void __builtin_ia32_movntps (float *, v4sf) int __builtin_ia32_movmskps (v4sf) -@end example +@end smallexample The following built-in functions are available when @option{-msse} is used. @@ -5315,10 +6054,10 @@ Generates the @code{movhps} machine instruction as a store to memory. Generates the @code{movlps} machine instruction as a store to memory. @end table -The following built-in functions are available when @option{-mpni} is used. +The following built-in functions are available when @option{-msse3} is used. All of them generate the machine instruction that is part of the name. -@example +@smallexample v2df __builtin_ia32_addsubpd (v2df, v2df) v2df __builtin_ia32_addsubps (v2df, v2df) v2df __builtin_ia32_haddpd (v2df, v2df) @@ -5331,9 +6070,9 @@ v2df __builtin_ia32_movddup (v2df) v4sf __builtin_ia32_movshdup (v4sf) v4sf __builtin_ia32_movsldup (v4sf) void __builtin_ia32_mwait (unsigned int, unsigned int) -@end example +@end smallexample -The following built-in functions are available when @option{-mpni} is used. +The following built-in functions are available when @option{-msse3} is used. @table @code @item v2df __builtin_ia32_loadddup (double const *) @@ -5343,7 +6082,7 @@ Generates the @code{movddup} machine instruction as a load from memory. The following built-in functions are available when @option{-m3dnow} is used. All of them generate the machine instruction that is part of the name. -@example +@smallexample void __builtin_ia32_femms (void) v8qi __builtin_ia32_pavgusb (v8qi, v8qi) v2si __builtin_ia32_pf2id (v2sf) @@ -5364,20 +6103,20 @@ v2sf __builtin_ia32_pfsub (v2sf, v2sf) v2sf __builtin_ia32_pfsubr (v2sf, v2sf) v2sf __builtin_ia32_pi2fd (v2si) v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) -@end example +@end smallexample The following built-in functions are available when both @option{-m3dnow} and @option{-march=athlon} are used. All of them generate the machine instruction that is part of the name. -@example +@smallexample v2si __builtin_ia32_pf2iw (v2sf) v2sf __builtin_ia32_pfnacc (v2sf, v2sf) v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) v2sf __builtin_ia32_pi2fw (v2si) v2sf __builtin_ia32_pswapdsf (v2sf) v2si __builtin_ia32_pswapdsi (v2si) -@end example +@end smallexample @node PowerPC AltiVec Built-in Functions @subsection PowerPC AltiVec Built-in Functions @@ -6618,7 +7357,7 @@ For compatibility with other compilers, GCC allows you to define a structure or union that contains, as fields, structures and unions without names. For example: -@example +@smallexample struct @{ int a; union @{ @@ -6627,7 +7366,7 @@ struct @{ @}; int d; @} foo; -@end example +@end smallexample In this example, the user would be able to access members of the unnamed union with code like @samp{foo.b}. Note that only unnamed structs and @@ -6637,14 +7376,14 @@ unions are allowed, you may not have, for example, an unnamed You must never create such structures that cause ambiguous field definitions. For example, this structure: -@example +@smallexample struct @{ int a; struct @{ int a; @}; @} foo; -@end example +@end smallexample It is ambiguous which @code{a} is being referred to with @samp{foo.a}. Such constructs are not supported and must be avoided. In the future, @@ -6668,11 +7407,11 @@ is not available everywhere. At the user level, the extension is visible with a new storage class keyword: @code{__thread}. For example: -@example +@smallexample __thread int i; extern __thread struct state s; static __thread char *p; -@end example +@end smallexample The @code{__thread} specifier may be used alone, with the @code{extern} or @code{static} specifiers, but with no other storage class specifier. @@ -6935,8 +7674,10 @@ Predefined Macros,cpp,The GNU C Preprocessor}). * Bound member functions:: You can extract a function pointer to the method denoted by a @samp{->*} or @samp{.*} expression. * C++ Attributes:: Variable, function, and type attributes for C++ only. +* Strong Using:: Strong using-directives for namespace composition. +* Offsetof:: Special syntax for implementing @code{offsetof}. * Java Exceptions:: Tweaking exception handling to work with Java. -* Deprecated Features:: Things might disappear from g++. +* Deprecated Features:: Things will disappear from g++. * Backwards Compatibility:: Compatibilities with earlier definitions of C++. @end menu @@ -6964,9 +7705,9 @@ These operations are not primitive in ordinary C++, since you can use a macro to return the minimum of two things in C++, as in the following example. -@example +@smallexample #define MIN(X,Y) ((X) < (Y) ? : (X) : (Y)) -@end example +@end smallexample @noindent You might then use @w{@samp{int min = MIN (i, j);}} to set @var{min} to @@ -7011,11 +7752,11 @@ within a sequence point. In most expressions, it is intuitively obvious what is a read and what is a write. For instance -@example +@smallexample volatile int *dst = @var{somevalue}; volatile int *src = @var{someothervalue}; *dst = *src; -@end example +@end smallexample @noindent will cause a read of the volatile object pointed to by @var{src} and stores the @@ -7026,10 +7767,10 @@ larger than @code{int}. Less obvious expressions are where something which looks like an access is used in a void context. An example would be, -@example +@smallexample volatile int *src = @var{somevalue}; *src; -@end example +@end smallexample With C, such expressions are rvalues, and as rvalues cause a read of the object, GCC interprets this as a read of the volatile being pointed @@ -7044,14 +7785,14 @@ pointer to volatile object of complete type in a void context as a read of the object. When the object has incomplete type, G++ issues a warning. -@example +@smallexample struct S; struct T @{int m;@}; volatile S *ptr1 = @var{somevalue}; volatile T *ptr2 = @var{somevalue}; *ptr1; *ptr2; -@end example +@end smallexample In this example, a warning is issued for @code{*ptr1}, and @code{*ptr2} causes a read of the object pointed to. If you wish to force an error on @@ -7072,7 +7813,7 @@ an rvalue. @cindex restricted references @cindex restricted this pointer -As with gcc, g++ understands the C99 feature of restricted pointers, +As with the C front end, G++ understands the C99 feature of restricted pointers, specified with the @code{__restrict__}, or @code{__restrict} type qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} language flag, @code{restrict} is not a keyword in C++. @@ -7081,12 +7822,12 @@ In addition to allowing restricted pointers, you can specify restricted references, which indicate that the reference is not aliased in the local context. -@example +@smallexample void fn (int *__restrict__ rptr, int &__restrict__ rref) @{ /* @r{@dots{}} */ @} -@end example +@end smallexample @noindent In the body of @code{fn}, @var{rptr} points to an unaliased integer and @@ -7095,12 +7836,12 @@ In the body of @code{fn}, @var{rptr} points to an unaliased integer and You may also specify whether a member function's @var{this} pointer is unaliased by using @code{__restrict__} as a member function qualifier. -@example +@smallexample void T::fn () __restrict__ @{ /* @r{@dots{}} */ @} -@end example +@end smallexample @noindent Within the body of @code{T::fn}, @var{this} will have the effective @@ -7175,7 +7916,7 @@ but there are other options as well. @end table When used with GNU ld version 2.8 or later on an ELF system such as -Linux/GNU or Solaris 2, or on Microsoft Windows, duplicate copies of +GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of these constructs will be discarded at link time. This is known as COMDAT support. @@ -7193,37 +7934,24 @@ almost certainly break things. another way to control placement of these constructs. @node C++ Interface -@section Declarations and Definitions in One Header +@section #pragma interface and implementation @cindex interface and implementation headers, C++ @cindex C++ interface and implementation headers -C++ object definitions can be quite complex. In principle, your source -code will need two kinds of things for each object that you use across -more than one source file. First, you need an @dfn{interface} -specification, describing its structure with type declarations and -function prototypes. Second, you need the @dfn{implementation} itself. -It can be tedious to maintain a separate interface description in a -header file, in parallel to the actual implementation. It is also -dangerous, since separate interface and implementation definitions may -not remain parallel. - @cindex pragmas, interface and implementation -With GNU C++, you can use a single header file for both purposes. -@quotation -@emph{Warning:} The mechanism to specify this is in transition. For the -nonce, you must use one of two @code{#pragma} commands; in a future -release of GNU C++, an alternative mechanism will make these -@code{#pragma} commands unnecessary. -@end quotation +@code{#pragma interface} and @code{#pragma implementation} provide the +user with a way of explicitly directing the compiler to emit entities +with vague linkage (and debugging information) in a particular +translation unit. -The header file contains the full definitions, but is marked with -@samp{#pragma interface} in the source code. This allows the compiler -to use the header file only as an interface specification when ordinary -source files incorporate it with @code{#include}. In the single source -file where the full implementation belongs, you can use either a naming -convention or @samp{#pragma implementation} to indicate this alternate -use of the header file. +@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in +most cases, because of COMDAT support and the ``key method'' heuristic +mentioned in @ref{Vague Linkage}. Using them can actually cause your +program to grow due to unnecesary out-of-line copies of inline +functions. Currently the only benefit of these @code{#pragma}s is +reduced duplication of debugging information, and that should be +addressed soon on DWARF 2 targets with the use of COMDAT sections. @table @code @item #pragma interface @@ -7273,9 +8001,6 @@ an implementation file whenever you would include it from implementation}. This was deemed to be more trouble than it was worth, however, and disabled. -If you use an explicit @samp{#pragma implementation}, it must appear in -your source file @emph{before} you include the affected header files. - Use the string argument if you want a single implementation file to include code from multiple header files. (You must also use @samp{#include} to include the header file; @samp{#pragma @@ -7293,10 +8018,10 @@ multiple implementation files. effect on function inlining. If you define a class in a header file marked with @samp{#pragma -interface}, the effect on a function defined in that class is similar to -an explicit @code{extern} declaration---the compiler emits no code at -all to define an independent version of the function. Its definition -is used only for inlining with its callers. +interface}, the effect on an inline function defined in that class is +similar to an explicit @code{extern} declaration---the compiler emits +no code at all to define an independent version of the function. Its +definition is used only for inlining with its callers. @opindex fno-implement-inlines Conversely, when you include the same header file in a main source file @@ -7316,7 +8041,7 @@ intelligence from the environment than one usually finds on a UNIX system. Somehow the compiler and linker have to make sure that each template instance occurs exactly once in the executable if it is needed, and not at all otherwise. There are two basic approaches to this -problem, which I will refer to as the Borland model and the Cfront model. +problem, which are referred to as the Borland model and the Cfront model. @table @asis @item Borland model @@ -7352,11 +8077,11 @@ compiled separately. @end table When used with GNU ld version 2.8 or later on an ELF system such as -Linux/GNU or Solaris 2, or on Microsoft Windows, g++ supports the -Borland model. On other systems, g++ implements neither automatic +GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the +Borland model. On other systems, G++ implements neither automatic model. -A future version of g++ will support a hybrid model whereby the compiler +A future version of G++ will support a hybrid model whereby the compiler will emit any instantiations for which the template definition is included in the compile, and store template definitions and instantiation context information into the object file for the rest. @@ -7406,14 +8131,14 @@ that define the templates themselves; you can put all of the explicit instantiations you need into one big file; or you can create small files like -@example +@smallexample #include "Foo.h" #include "Foo.cc" template class Foo<int>; template ostream& operator << (ostream&, const Foo<int>&); -@end example +@end smallexample for each of the instances you need, and create a template instantiation library from those. @@ -7427,7 +8152,7 @@ compile it without @option{-fno-implicit-templates} so you get all of the instances required by your explicit instantiations (but not by any other files) without having to specify them as well. -g++ has extended the template instantiation syntax given in the ISO +G++ has extended the template instantiation syntax given in the ISO standard to allow forward declaration of explicit instantiations (with @code{extern}), instantiation of the compiler support data for a template class (i.e.@: the vtable) without instantiating any of its @@ -7435,21 +8160,18 @@ members (with @code{inline}), and instantiation of only the static data members of a template class, without the support data or member functions (with (@code{static}): -@example +@smallexample extern template int max (int, int); inline template class Foo<int>; static template class Foo<int>; -@end example +@end smallexample @item -Do nothing. Pretend g++ does implement automatic instantiation +Do nothing. Pretend G++ does implement automatic instantiation management. Code written for the Borland model will work fine, but each translation unit will contain instances of each of the templates it uses. In a large program, this can lead to an unacceptable amount of code duplication. - -@xref{C++ Interface,,Declarations and Definitions in One Header}, for -more discussion of these pragmas. @end enumerate @node Bound member functions @@ -7475,21 +8197,21 @@ virtual function calls. The syntax for this extension is -@example +@smallexample extern A a; extern int (A::*fp)(); typedef int (*fptr)(A *); fptr p = (fptr)(a.*fp); -@end example +@end smallexample For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), no object is needed to obtain the address of the function. They can be converted to function pointers directly: -@example +@smallexample fptr p1 = (fptr)(&A::foo); -@end example +@end smallexample @opindex Wno-pmf-conversions You must specify @option{-Wno-pmf-conversions} to use this extension. @@ -7535,6 +8257,69 @@ interface table mechanism, instead of regular virtual table dispatch. @end table +See also @xref{Strong Using}. + +@node Strong Using +@section Strong Using + +@strong{Caution:} The semantics of this extension are not fully +defined. Users should refrain from using this extension as its +semantics may change subtly over time. It is possible that this +extension wil be removed in future versions of G++. + +A using-directive with @code{__attribute ((strong))} is stronger +than a normal using-directive in two ways: + +@itemize @bullet +@item +Templates from the used namespace can be specialized as though they were members of the using namespace. + +@item +The using namespace is considered an associated namespace of all +templates in the used namespace for purposes of argument-dependent +name lookup. +@end itemize + +This is useful for composing a namespace transparently from +implementation namespaces. For example: + +@smallexample +namespace std @{ + namespace debug @{ + template <class T> struct A @{ @}; + @} + using namespace debug __attribute ((__strong__)); + template <> struct A<int> @{ @}; // ok to specialize + + template <class T> void f (A<T>); +@} + +int main() +@{ + f (std::A<float>()); // lookup finds std::f + f (std::A<int>()); +@} +@end smallexample + +@node Offsetof +@section Offsetof + +G++ uses a syntactic extension to implement the @code{offsetof} macro. + +In particular: + +@smallexample + __offsetof__ (expression) +@end smallexample + +is equivalent to the parenthesized expression, except that the +expression is considered an integral constant expression even if it +contains certain operators that are not normally permitted in an +integral constant expression. Users should never use +@code{__offsetof__} directly; the only valid use of +@code{__offsetof__} is to implement the @code{offsetof} macro in +@code{<stddef.h>}. + @node Java Exceptions @section Java Exceptions @@ -7586,10 +8371,10 @@ that are now deprecated: @table @code @item -fexternal-templates @itemx -falt-external-templates -These are two of the many ways for g++ to implement template +These are two of the many ways for G++ to implement template instantiation. @xref{Template Instantiation}. The C++ standard clearly defines how template definitions have to be organized across -implementation units. g++ has an implicit instantiation mechanism that +implementation units. G++ has an implicit instantiation mechanism that should work just fine for standard-conforming code. @item -fstrict-prototype @@ -7601,18 +8386,20 @@ it is required for backwards compatibility @xref{Backwards Compatibility}. @end table The named return value extension has been deprecated, and is now -removed from g++. +removed from G++. The use of initializer lists with new expressions has been deprecated, -and is now removed from g++. +and is now removed from G++. Floating and complex non-type template parameters have been deprecated, -and are now removed from g++. +and are now removed from G++. + +The implicit typename extension has been deprecated and is now +removed from G++. -The implicit typename extension has been deprecated and will be removed -from g++ at some point. In some cases g++ determines that a dependent -type such as @code{TPL<T>::X} is a type without needing a -@code{typename} keyword, contrary to the standard. +The use of default arguments in function pointers, function typedefs and +and other places where they are not permitted by the standard is +deprecated and will be removed from a future version of G++. @node Backwards Compatibility @section Backwards Compatibility diff --git a/contrib/gcc/doc/fragments.texi b/contrib/gcc/doc/fragments.texi index c9ebcf9..160ffed 100644 --- a/contrib/gcc/doc/fragments.texi +++ b/contrib/gcc/doc/fragments.texi @@ -13,7 +13,8 @@ construct the file @file{Makefile} from the template file 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}; @xref{System Config}. +@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 diff --git a/contrib/gcc/doc/frontends.texi b/contrib/gcc/doc/frontends.texi index 1ee5685..0e4dfe5 100644 --- a/contrib/gcc/doc/frontends.texi +++ b/contrib/gcc/doc/frontends.texi @@ -1,70 +1,61 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001 Free Software Foundation, Inc. +@c 1999, 2000, 2001, 2004 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 Compile C, C++, Objective-C, Ada, Fortran, Java, or treelang +@chapter Programming Languages Supported by GCC -@cindex Objective-C +@cindex GCC +@cindex GNU Compiler Collection +@cindex GNU C Compiler +@cindex Ada @cindex Fortran @cindex Java -@cindex Ada +@cindex Objective-C @cindex treelang -Several versions of the compiler (C, C++, Objective-C, Ada, -Fortran, Java and treelang) are integrated; this is why we use the name -``GNU Compiler Collection''. GCC can compile programs written in any of these -languages. The Ada, Fortran, Java and treelang compilers are described in -separate manuals. - -@cindex GCC -``GCC'' is a common shorthand term for the GNU Compiler Collection. This is both -the most general name for the compiler, and the name used when the -emphasis is on compiling C programs (as the abbreviation formerly -stood for ``GNU C Compiler''). +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, Java, Fortran, and Ada. + +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 +@cindex Pascal +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 Pascal, +Mercury, and COBOL. To use these, they must be built together with +GCC proper. @cindex C++ @cindex G++ -When referring to C++ compilation, it is usual to call the compiler -``G++''. Since there is only one compiler, it is also accurate to call -it ``GCC'' no matter what the language context; however, the term -``G++'' is more useful when the emphasis is on compiling C++ programs. - @cindex Ada @cindex GNAT -Similarly, when we talk about Ada compilation, we usually call the -compiler ``GNAT'', for the same reasons. - -We use the name ``GCC'' to refer to the compilation system as a -whole, and more specifically to the language-independent part of the -compiler. For example, we refer to the optimization options as -affecting the behavior of ``GCC'' or sometimes just ``the compiler''. - -Front ends for other languages, such as Mercury and Pascal exist but -have not yet been integrated into GCC@. These front ends, like that for C++, -are built in subdirectories of GCC and link to it. The result is an -integrated compiler that can compile programs written in C, C++, -Objective-C, or any of the languages for which you have installed front -ends. - -In this manual, we only discuss the options for the C, Objective-C, and -C++ compilers and those of the GCC core. Consult the documentation -of the other front ends for the options to use when compiling programs -written in other languages. +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 -G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object -code directly from your C++ program source. There is no intermediate C -version of the program. (By contrast, for example, some other -implementations use a program that generates a C program from your C++ -source.) Avoiding an intermediate C representation of the program means -that you get better object code, and better debugging information. The -GNU debugger, GDB, works with this information in the object code to -give you comprehensive C++ source-level editing capabilities -(@pxref{C,,C and C++,gdb.info, Debugging with GDB}). - -@c FIXME! Someone who knows something about Objective-C ought to put in -@c a paragraph or two about it here, and move the index entry down when -@c there is more to point to than the general mention in the 1st par. +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++, and +Objective-C languages. diff --git a/contrib/gcc/doc/gcc.texi b/contrib/gcc/doc/gcc.texi index 721150a..07dfd08 100644 --- a/contrib/gcc/doc/gcc.texi +++ b/contrib/gcc/doc/gcc.texi @@ -35,34 +35,13 @@ @syncodeindex pg cp @syncodeindex tp cp -@c %**end of header - -@c Use with @@smallbook. - -@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. +@paragraphindent 1 -@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 - -@c Change the font used for @def... commands, since the default -@c proportional one used is bad for names starting __. -@tex -\global\setfont\defbf\ttbshape{10}{\magstep1} -@end tex +@c %**end of header @copying Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. +1999, 2000, 2001, 2002, 2003, 2004 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 @@ -89,21 +68,18 @@ included in the section entitled ``GNU Free Documentation License''. @end direntry This file documents the use of the GNU compilers. @sp 1 -Published by the Free Software Foundation@* -59 Temple Place - Suite 330@* -Boston, MA 02111-1307 USA -@sp 1 @insertcopying @sp 1 @end ifnottex @setchapternewpage odd +@shorttitlepage Using the GNU Compiler Collection (GCC) @titlepage @center @titlefont{Using the GNU Compiler Collection} @sp 2 -@center Richard M. Stallman +@center by Richard M. Stallman and the GCC Developer Community @sp 3 -@center Last updated 30 December 2002 +@center Last updated 23 May 2004 @sp 1 @center for GCC @value{version-GCC} @@ -111,15 +87,30 @@ Boston, MA 02111-1307 USA @vskip 0pt plus 1filll For GCC Version @value{version-GCC}@* @sp 1 -Published by the Free Software Foundation @* -59 Temple Place---Suite 330@* -Boston, MA 02111-1307, USA@* -Last printed April, 1998.@* -Printed copies are available for $50 each.@* -@c Update this ISBN when printing a new edition. +Published by: +@multitable @columnfractions 0.5 0.5 +@item GNU Press +@tab Website: www.gnupress.org +@item a division of the +@tab General: @tex press@@gnu.org @end tex +@item Free Software Foundation +@tab Orders: @tex sales@@gnu.org @end tex +@item 59 Temple Place Suite 330 +@tab Tel 617-542-5942 +@item Boston, MA 02111-1307 USA +@tab Fax 617-542-2652 +@end multitable +@sp 2 @ifset FSFPRINT -ISBN 1-882114-37-X +@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 diff --git a/contrib/gcc/doc/gccint.texi b/contrib/gcc/doc/gccint.texi index b6bec09..5864e5f 100644 --- a/contrib/gcc/doc/gccint.texi +++ b/contrib/gcc/doc/gccint.texi @@ -23,29 +23,6 @@ @c %**end of header -@c Use with @@smallbook. - -@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 - -@c Change the font used for @def... commands, since the default -@c proportional one used is bad for names starting __. -@tex -\global\setfont\defbf\ttbshape{10}{\magstep1} -@end tex - @copying Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. @@ -75,10 +52,6 @@ included in the section entitled ``GNU Free Documentation License''. @end direntry This file documents the internals of the GNU compilers. @sp 1 -Published by the Free Software Foundation@* -59 Temple Place - Suite 330@* -Boston, MA 02111-1307 USA -@sp 1 @insertcopying @end ifnottex @@ -86,9 +59,9 @@ Boston, MA 02111-1307 USA @titlepage @center @titlefont{GNU Compiler Collection Internals} @sp 2 -@center Richard M. Stallman +@center by Richard M. Stallman and the GCC Developer Community @sp 3 -@center Last updated 28 December 2002 +@center Last updated 23 May 2004 @sp 1 @center for GCC @value{version-GCC} @@ -96,16 +69,6 @@ Boston, MA 02111-1307 USA @vskip 0pt plus 1filll For GCC Version @value{version-GCC}@* @sp 1 -Published by the Free Software Foundation @* -59 Temple Place---Suite 330@* -Boston, MA 02111-1307, USA@* -Last printed April, 1998.@* -Printed copies are available for $50 each.@* -@c Update this ISBN when printing a new edition. -@ifset FSFPRINT -ISBN 1-882114-37-X -@end ifset -@sp 1 @insertcopying @end titlepage @summarycontents @@ -140,6 +103,7 @@ Additional tutorial information is linked to from * 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. * Passes:: Order of passes, what they do, and what each file is for. @@ -168,6 +132,7 @@ Additional tutorial information is linked to from @include contribute.texi @include portability.texi @include interface.texi +@include libgcc.texi @include languages.texi @include sourcebuild.texi @include passes.texi diff --git a/contrib/gcc/doc/gcov.texi b/contrib/gcc/doc/gcov.texi index 85d5289..cd47f68 100644 --- a/contrib/gcc/doc/gcov.texi +++ b/contrib/gcc/doc/gcov.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1996, 1997, 1999, 2000, 2001, -@c 2002, 2003 Free Software Foundation, Inc. +@c 2002, 2003, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -120,6 +120,7 @@ gcov @r{[}@var{options}@r{]} @var{sourcefile} @ignore @c man begin SYNOPSIS gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] + [@option{-a}|@option{--all-blocks}] [@option{-b}|@option{--branch-probabilities}] [@option{-c}|@option{--branch-counts}] [@option{-n}|@option{--no-output}] @@ -127,6 +128,7 @@ gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] [@option{-p}|@option{--preserve-paths}] [@option{-f}|@option{--function-summaries}] [@option{-o}|@option{--object-directory} @var{directory|file}] @var{sourcefile} + [@option{-u}|@option{--unconditional-branches}] @c man end @c man begin SEEALSO gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}. @@ -145,11 +147,19 @@ exit without doing any further processing. Display the @command{gcov} version number (on the standard output), and exit without doing any further processing. +@item -a +@itemx --all-blocks +Write individual execution counts for every basic block. Normally gcov +outputs execution counts only for the main blocks of a line. With this +option you can determine if blocks within a single line are not being +executed. + @item -b @itemx --branch-probabilities Write branch frequencies to the output file, and write branch summary info to the standard output. This option allows you to see how often -each branch in your program was taken. +each branch in your program was taken. Unconditional branches will not +be shown, unless the @option{-u} option is given. @item -c @itemx --branch-counts @@ -166,7 +176,9 @@ Create long file names for included source files. For example, if the header file @file{x.h} contains code, and was included in the file @file{a.c}, then running @command{gcov} on the file @file{a.c} will produce an output file called @file{a.c##x.h.gcov} instead of @file{x.h.gcov}. -This can be useful if @file{x.h} is included in multiple source files. +This can be useful if @file{x.h} is included in multiple source +files. If you uses the @samp{-p} option, both the including and +included file names will be complete path names. @item -p @itemx --preserve-paths @@ -185,24 +197,33 @@ Output summaries for each function in addition to the file level summary. @itemx --object-directory @var{directory} @itemx --object-file @var{file} Specify either the directory containing the gcov data files, or the -object path name. The @file{.bb}, @file{.bbg}, and -@file{.da} data files are searched for using this option. If a directory +object path name. The @file{.gcno}, and +@file{.gcda} data files are searched for using this option. If a directory is specified, the data files are in that directory and named after the source file name, without its extension. If a file is specified here, the data files are named after that file, without its extension. If this option is not supplied, it defaults to the current directory. +@item -u +@itemx --unconditional-branches +When branch counts are given, include those of unconditional branches. +Unconditional branches are normally not interesting. + @end table -@command{gcov} should be run with the current directory the same as that -when you invoked the compiler. Otherwise it will not be able to locate -the source files. @command{gcov} produces files called -@file{@var{mangledname}.gcov} in the current directory. These contain -the coverage information of the source file they correspond to. -One @file{.gcov} file is produced for each source file containing code, -which was compiled to produce the data files. The @file{.gcov} files -contain the ':' separated fields along with program source code. The -format is +@command{gcov} should be run with the current directory the same as that +when you invoked the compiler. Otherwise it will not be able to locate +the source files. @command{gcov} produces files called +@file{@var{mangledname}.gcov} in the current directory. These contain +the coverage information of the source file they correspond to. +One @file{.gcov} file is produced for each source file containing code, +which was compiled to produce the data files. The @var{mangledname} part +of the output file name is usually simply the source file name, but can +be something more complicated if the @samp{-l} or @samp{-p} options are +given. Refer to those options for details. + +The @file{.gcov} files contain the ':' separated fields along with +program source code. The format is @smallexample @var{execution_count}:@var{line_number}:@var{source line text} @@ -228,8 +249,8 @@ information needed by gcov. These additional files are placed in the directory where the object file is located. Running the program will cause profile output to be generated. For each -source file compiled with @option{-fprofile-arcs}, an accompanying @file{.da} -file will be placed in the object file directory. +source file compiled with @option{-fprofile-arcs}, an accompanying +@file{.gcda} file will be placed in the object file directory. Running @command{gcov} with your program's source file names as arguments will now produce a listing of the code along with frequency of execution @@ -249,26 +270,79 @@ Here is a sample: @smallexample -: 0:Source:tmp.c - -: 0:Object:tmp.bb + -: 0:Graph:tmp.gcno + -: 0:Data:tmp.gcda + -: 0:Runs:1 + -: 0:Programs:1 + -: 1:#include <stdio.h> + -: 2: + -: 3:int main (void) +function main called 1 returned 1 blocks executed 75% + 1: 4:@{ + 1: 5: int i, total; + -: 6: + 1: 7: total = 0; + -: 8: + 11: 9: for (i = 0; i < 10; i++) + 10: 10: total += i; + -: 11: + 1: 12: if (total != 45) + #####: 13: printf ("Failure\n"); + -: 14: else + 1: 15: printf ("Success\n"); + 1: 16: return 0; + -: 17:@} +@end smallexample + +When you use the @option{-a} option, you will get individual block +counts, and the output looks like this: + +@smallexample + -: 0:Source:tmp.c + -: 0:Graph:tmp.gcno + -: 0:Data:tmp.gcda + -: 0:Runs:1 + -: 0:Programs:1 -: 1:#include <stdio.h> -: 2: -: 3:int main (void) +function main called 1 returned 1 blocks executed 75% 1: 4:@{ + 1: 4-block 0 1: 5: int i, total; - -: 6: + -: 6: 1: 7: total = 0; - -: 8: + -: 8: 11: 9: for (i = 0; i < 10; i++) + 11: 9-block 0 10: 10: total += i; - -: 11: + 10: 10-block 0 + -: 11: 1: 12: if (total != 45) + 1: 12-block 0 #####: 13: printf ("Failure\n"); + $$$$$: 13-block 0 -: 14: else 1: 15: printf ("Success\n"); + 1: 15-block 0 1: 16: return 0; - 1: 17:@} + 1: 16-block 0 + -: 17:@} @end smallexample +In this mode, each basic block is only shown on one line -- the last +line of the block. A multi-line block will only contribute to the +execution count of that last line, and other lines will not be shown +to contain code, unless previous blocks end on those lines. +The total execution count of a line is shown and subsequent lines show +the execution counts for individual blocks that end on that line. After each +block, the branch and call counts of the block will be shown, if the +@option{-b} option is given. + +Because of the way GCC instruments calls, a call count can be shown +after a line with no individual blocks. +As you can see, line 13 contains a basic block that was not executed. + @need 450 When you use the @option{-b} option, your output looks like this: @@ -285,31 +359,34 @@ Here is a sample of a resulting @file{tmp.c.gcov} file: @smallexample -: 0:Source:tmp.c - -: 0:Object:tmp.bb + -: 0:Graph:tmp.gcno + -: 0:Data:tmp.gcda + -: 0:Runs:1 + -: 0:Programs:1 -: 1:#include <stdio.h> -: 2: -: 3:int main (void) +function main called 1 returned 1 blocks executed 75% 1: 4:@{ 1: 5: int i, total; - -: 6: + -: 6: 1: 7: total = 0; - -: 8: + -: 8: 11: 9: for (i = 0; i < 10; i++) -branch 0: taken 90% -branch 1: taken 100% -branch 2: taken 100% +branch 0 taken 91% (fallthrough) +branch 1 taken 9% 10: 10: total += i; - -: 11: + -: 11: 1: 12: if (total != 45) -branch 0: taken 100% +branch 0 taken 0% (fallthrough) +branch 1 taken 100% #####: 13: printf ("Failure\n"); -call 0: never executed -branch 1: never executed +call 0 never executed -: 14: else 1: 15: printf ("Success\n"); -call 0: returns 100% +call 0 called 1 returned 100% 1: 16: return 0; - 1: 17:@} + -: 17:@} @end smallexample For each basic block, a line is printed after the last line of the basic @@ -333,7 +410,7 @@ of times the call was executed will be printed. This will usually be and thus may not return every time they are called. The execution counts are cumulative. If the example program were -executed again without removing the @file{.da} file, the count for the +executed again without removing the @file{.gcda} file, the count for the number of times each line in the source was executed would be added to the results of the previous run(s). This is potentially useful in several ways. For example, it could be used to accumulate data over a @@ -341,9 +418,9 @@ number of program runs as part of a test verification suite, or to provide more accurate long-term information over a large number of program runs. -The data in the @file{.da} files is saved immediately before the program +The data in the @file{.gcda} files is saved immediately before the program exits. For each source file compiled with @option{-fprofile-arcs}, the -profiling code first attempts to read in an existing @file{.da} file; if +profiling code first attempts to read in an existing @file{.gcda} file; if the file doesn't match the executable (differing number of basic block counts) it will ignore the contents of the file. It then adds in the new execution counts and finally writes the data to the file. @@ -386,119 +463,50 @@ executed 100 times. In one sense this result is correct, because there was only one instruction representing all four of these lines. However, the output does not indicate how many times the result was 0 and how many times the result was 1. + +Inlineable functions can create unexpected line counts. Line counts are +shown for the source code of the inlineable function, but what is shown +depends on where the function is inlined, or if it is not inlined at all. + +If the function is not inlined, the compiler must emit an out of line +copy of the function, in any object file that needs it. If +@file{fileA.o} and @file{fileB.o} both contain out of line bodies of a +particular inlineable function, they will also both contain coverage +counts for that function. When @file{fileA.o} and @file{fileB.o} are +linked together, the linker will, on many systems, select one of those +out of line bodies for all calls to that function, and remove or ignore +the other. Unfortunately, it will not remove the coverage counters for +the unused function body. Hence when instrumented, all but one use of +that function will show zero counts. + +If the function is inlined in several places, the block structure in +each location might not be the same. For instance, a condition might +now be calculable at compile time in some instances. Because the +coverage of all the uses of the inline function will be shown for the +same source lines, the line counts themselves might seem inconsistent. + @c man end @node Gcov Data Files @section Brief description of @command{gcov} data files -@command{gcov} uses three files for doing profiling. The names of these -files are derived from the original @emph{source} file by substituting -the file suffix with either @file{.bb}, @file{.bbg}, or @file{.da}. All -of these files are placed in the same directory as the source file, and -contain data stored in a platform-independent method. - -The @file{.bb} and @file{.bbg} files are generated when the source file -is compiled with the GCC @option{-ftest-coverage} option. The -@file{.bb} file contains a list of source files (including headers), -functions within those files, and line numbers corresponding to each -basic block in the source file. - -The @file{.bb} file format consists of several lists of 4-byte integers -which correspond to the line numbers of each basic block in the file. -Each list is terminated by a line number of 0. A line number of -@minus{}1 is used to designate that the source file name (padded to a -4-byte boundary and followed by another @minus{}1) follows. In -addition, a line number of @minus{}2 is used to designate that the name -of a function (also padded to a 4-byte boundary and followed by a -@minus{}2) follows. - -The @file{.bbg} file is used to reconstruct the program flow graph for -the source file. It contains a list of the program flow arcs (possible -branches taken from one basic block to another) for each function which, -in combination with the @file{.bb} file, enables gcov to reconstruct the -program flow. - -In the @file{.bbg} file, the format is: -@smallexample - name of function #0 - checksum of function #0 - number of basic blocks for function #0 (4-byte number) - total number of arcs for function #0 (4-byte number) - count of arcs in basic block #0 (4-byte number) - destination basic block of arc #0 (4-byte number) - flag bits (4-byte number) - destination basic block of arc #1 (4-byte number) - flag bits (4-byte number) - @dots{} - destination basic block of arc #N (4-byte number) - flag bits (4-byte number) - count of arcs in basic block #1 (4-byte number) - destination basic block of arc #0 (4-byte number) - flag bits (4-byte number) - @dots{} -@end smallexample - -A @minus{}1 (stored as a 4-byte number) is used to separate each function's -list of basic blocks, and to verify that the file has been read -correctly. - -The function name is stored as a @minus{}1 (4 bytes), the length (4 bytes), -the name itself (padded to 4-byte boundary) followed by a @minus{}1 (4 bytes). - -The flags are defined as follows: -@itemize -@item bit0 -On function spanning tree +@command{gcov} uses two files for profiling. The names of these files +are derived from the original @emph{object} file by substituting the +file suffix with either @file{.gcno}, or @file{.gcda}. All of these files +are placed in the same directory as the object file, and contain data +stored in a platform-independent format. -@item bit1 -Is a fake edge +The @file{.gcno} file is generated when the source file is compiled with +the GCC @option{-ftest-coverage} option. It contains information to +reconstruct the basic block graphs and assign source line numbers to +blocks. -@item bit2 -Is the fall through edge from one block to its immediate successor. - -@item bit3-bit31 -For future expansion - -@end itemize - -The @file{.da} file is generated when a program containing object files +The @file{.gcda} file is generated when a program containing object files built with the GCC @option{-fprofile-arcs} option is executed. A -separate @file{.da} file is created for each source file compiled with -this option, and the name of the @file{.da} file is stored as an -absolute pathname in the resulting object file. This path name is -derived from the object file name by substituting a @file{.da} suffix. - -The @file{.da} consists of one or more blocks with the following -structure: -@smallexample - "magic" number @minus{}123 (4-byte number) - number of functions (4-byte number) - length of the "extension block" in bytes - extension block (variable length) - name of function #0 (the same format as in .bbg file) - checksum of function #0 - number of instrumented arcs (4-byte number) - count of arc #0 (8-byte number) - count of arc #1 (8-byte number) - @dots{} - count of arc #M_0 (8-byte number) - name of function #1 (the same format as in .bbg file) - checksum of function #1 - @dots{} -@end smallexample -Multiple program runs might merge data into a single block, or might -append a new block. The current structure of the extension block is as -follows: -@smallexample - number of instrumented arcs in whole program (4-byte number) - sum all of instrumented arcs in whole program (8-byte number) - maximal value of counter in whole program (8-byte number) - number of instrumented arcs in the object file (4-byte number) - sum all of instrumented arcs in the object file (8-byte number) - maximal value of counter in the object file (8-byte number) -@end smallexample - -All three of these files use the functions in @file{gcov-io.h} to store -integers; the functions in this header provide a machine-independent -mechanism for storing and retrieving data from a stream. +separate @file{.gcda} file is created for each object file compiled with +this option. It contains arc transition counts, and some summary +information. +The full details of the file format is specified in @file{gcov-io.h}, +and functions provided in that header file should be used to access the +coverage files. diff --git a/contrib/gcc/doc/gty.texi b/contrib/gcc/doc/gty.texi index 31d5252..2dc5b86 100644 --- a/contrib/gcc/doc/gty.texi +++ b/contrib/gcc/doc/gty.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 2002, 2003 +@c Copyright (C) 2002, 2003, 2004 @c Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -10,7 +10,8 @@ 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. +source code and using this information to perform garbage collection and +implement precompiled headers. A full C parser would be too overcomplicated for this task, so a limited subset of C is interpreted and special markers are used to determine @@ -47,7 +48,7 @@ These markers can be placed: @item In a structure definition, before the open brace; @item -In a global variable declaration, after the keyword @code{static} or +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. @@ -131,8 +132,19 @@ field really isn't ever used. @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}. For example, +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's +supposed to be a constant.) + +For example, @smallexample struct tree_binding GTY(()) @{ @@ -140,19 +152,15 @@ struct tree_binding GTY(()) 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)"))) scope; + @} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope; tree value; @}; @end smallexample -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's -supposed to be a constant.) - -Each @code{tag} 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 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. @findex param_is @findex use_param @@ -227,6 +235,39 @@ 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 chain_next +@findex chain_prev +@item chain_next +@itemx chain_prev + +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. The +machinery requires that taking the next item of the previous item +gives the original item. + +@findex reorder +@item reorder + +Some data structures depend on the relative ordering of pointers. If +the type 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 be of the type @code{void ()(void *, +void *, gt_pointer_operator, void *)}. The second parameter is the +pointed-to object; the third parameter is a routine that, given a +pointer, can update it to its new value. The fourth parameter is a +cookie to be passed to the third parameter. The first parameter is +the structure that contains the object, or the object itself if it is +a structure. + +No data structure may depend on the absolute value of pointers. Even +relying on relative orderings and using @code{reorder} functions can +be expensive. It is better to depend on properties of the data, like +an ID number or the hash of a string instead. + @findex special @item special @@ -270,19 +311,19 @@ 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 three cases: +machinery scans. There are three 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}. +the appropriate port's entries in @file{config.gcc}. @item For files shared by all front ends, this is done by adding the filename to the @code{GTFILES} variable in @file{Makefile.in}. -@item +@item For any other file used by a front end, this is done by adding the filename to the @code{gtfiles} variable defined in @file{config-lang.in}. For C, the file is @file{c-config-lang.in}. @@ -301,7 +342,7 @@ 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.c}, which is a generated file, so add it to -@code{ifiles} in @code{open_base_file} in @file{gengtype.c}. +@code{ifiles} in @code{open_base_file} in @file{gengtype.c}. 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. diff --git a/contrib/gcc/doc/hostconfig.texi b/contrib/gcc/doc/hostconfig.texi index 33c0a3b..5c38313 100644 --- a/contrib/gcc/doc/hostconfig.texi +++ b/contrib/gcc/doc/hostconfig.texi @@ -1,72 +1,119 @@ -@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001, 2002 Free Software Foundation, Inc. +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +@c 2000, 2001, 2002, 2003 Free Software Foundation, Inc. @c This is part of the GCC manual. -@c For copying conditions, see the file gcc.texi. +@c For copying conditions, see the file gccint.texi. @node Host Config -@chapter Host Configuration Headers +@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 can't 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}) +This host hook returns the address of some space in which a PCH may be +loaded with @samp{HOST_HOOKS_PCH_LOAD_PCH}. The space will need to +have @var{size} bytes. If insufficient space is available, +@samp{NULL} may be returned; the PCH machinery will try to find a +suitable address using a heuristic. + +The memory does not have to be available now. In fact, usually +@samp{HOST_HOOKS_PCH_LOAD_PCH} will already have been called. The memory +need only be available in future invocations of GCC. +@end deftypefn + +@deftypefn {Host Hook} bool HOST_HOOKS_GT_PCH_USE_ADDRESS (size_t @var{size}, void * @var{address}) +This host hook is called when a PCH file is about to be loaded. If +@var{address} is the address that would have been returned by +@samp{HOST_HOOKS_PCH_MEMORY_ADDRESS}, and @var{size} is smaller than +the maximum than @samp{HOST_HOOKS_PCH_MEMORY_ADDRESS} would have +accepted, return true, otherwise return false. + +In addition, free any address space reserved that isn't needed to hold +@var{size} bytes (whether or not true is returned). The PCH machinery will +use @samp{mmap} with @samp{MAP_FIXED} to load the PCH if @samp{HAVE_MMAP_FILE}, +or will use @samp{fread} otherwise. + +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 false. 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 + +@node Filesystem +@section Host Filesystem @cindex configuration file @cindex @file{xm-@var{machine}.h} -Host configuration headers contain macro definitions that describe the -machine and system on which the compiler is running. They are usually -unnecessary. Most of the things GCC needs to know about the host -system can be deduced by the @command{configure} script. - -If your host does need a special configuration header, it should be -named @file{xm-@var{machine}.h}, where @var{machine} is a short mnemonic -for the machine. Here are some macros which this header can define. +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 VMS -Define this macro if the host system is VMS@. - -@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 HAVE_DOS_BASED_FILE_SYSTEM -Define this macro 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. If you -define this macro, you probably need to define the next three macros too. - -@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 use semicolon (@samp{;}). +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. They are -used somewhat inconsistently throughout the compiler. If your system -behaves like Unix (only forward slash separates pathnames), define -neither of them. If your system behaves like DOS (both forward and -backward slash can be used), define @code{DIR_SEPARATOR} to @samp{/} -and @code{DIR_SEPARATOR_2} to @samp{\}. +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 @@ -86,14 +133,6 @@ 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 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 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 @@ -112,6 +151,46 @@ 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. +@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 SMALL_ARG_MAX Define this macro if the host system has a small limit on the total @@ -123,8 +202,3 @@ 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}. - -If you need to define only a few of these 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}. diff --git a/contrib/gcc/doc/include/gcc-common.texi b/contrib/gcc/doc/include/gcc-common.texi index 0d2cae6..49725ab 100644 --- a/contrib/gcc/doc/include/gcc-common.texi +++ b/contrib/gcc/doc/include/gcc-common.texi @@ -1,10 +1,10 @@ -@c Copyright (C) 2001, 2002 Free Software Foundation, Inc. +@c Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @c Common values used in the GCC manuals: -@set version-GCC 3.3.3 +@set version-GCC 3.4.2 @c DEVELOPMENT is set to indicate an in-development version, @c as compared to a release version. When making a release @@ -32,10 +32,23 @@ @end macro @end ifnottex -@c For FSF printing, define FSFPRINT. Also update the ISBNs and last -@c printing dates in gcc.texi and gccint.texi. +@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 diff --git a/contrib/gcc/doc/include/texinfo.tex b/contrib/gcc/doc/include/texinfo.tex index e9293f3..9500f18 100644 --- a/contrib/gcc/doc/include/texinfo.tex +++ b/contrib/gcc/doc/include/texinfo.tex @@ -3,7 +3,7 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2003-05-04.08} +\def\texinfoversion{2003-12-21.10} % % Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. @@ -23,21 +23,16 @@ % to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, % Boston, MA 02111-1307, USA. % -% In other words, you are welcome to use, share and improve this program. -% You are forbidden to forbid anyone else to use, share and improve -% what you give them. Help stamp out software-hoarding! -% +% As a special exception, when this file is read by TeX when processing +% a Texinfo source document, you may use the result without +% restriction. (This has been our intent since Texinfo was invented.) +% % Please try the latest version of texinfo.tex before submitting bug % reports; you can get the latest version from: -% ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex -% (and all GNU mirrors, see http://www.gnu.org/order/ftp.html) +% http://www.gnu.org/software/texinfo/ (the Texinfo home page), or % ftp://tug.org/tex/texinfo.tex -% (and all CTAN mirrors, see http://www.ctan.org), -% and /home/gd/gnu/doc/texinfo.tex on the GNU machines. -% -% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. -% -% The texinfo.tex in any given Texinfo distribution could well be out +% (and all CTAN mirrors, see http://www.ctan.org). +% The texinfo.tex in any given distribution could well be out % of date, so if that's what you're using, please check. % % Send bug reports to bug-texinfo@gnu.org. Please include including a @@ -59,6 +54,9 @@ % It is possible to adapt texinfo.tex for other languages, to some % extent. You can get the existing language-specific files from the % full Texinfo distribution. +% +% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. + \message{Loading texinfo [version \texinfoversion]:} @@ -85,10 +83,13 @@ \let\ptexend=\end \let\ptexequiv=\equiv \let\ptexexclam=\! +\let\ptexfootnote=\footnote \let\ptexgtr=> \let\ptexhat=^ \let\ptexi=\i \let\ptexindent=\indent +\let\ptexnoindent=\noindent +\let\ptexinsert=\insert \let\ptexlbrace=\{ \let\ptexless=< \let\ptexplus=+ @@ -101,6 +102,15 @@ % starts a new line in the output. \newlinechar = `^^J +% Use TeX 3.0's \inputlineno to get the line number, for better error +% messages, but if we're using an old version of TeX, don't do anything. +% +\ifx\inputlineno\thisisundefined + \let\linenumber = \empty % Pre-3.0. +\else + \def\linenumber{l.\the\inputlineno:\space} +\fi + % Set up fixed words for English if not already set. \ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi \ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi @@ -139,30 +149,28 @@ \ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi \ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi \ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi -\ifx\putwordDeftypevar\undefined\gdef\putwordDeftypevar{Variable}\fi \ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi -\ifx\putwordDeftypefun\undefined\gdef\putwordDeftypefun{Function}\fi % In some macros, we cannot use the `\? notation---the left quote is % in some cases the escape char. \chardef\colonChar = `\: \chardef\commaChar = `\, \chardef\dotChar = `\. -\chardef\equalChar = `\= \chardef\exclamChar= `\! \chardef\questChar = `\? \chardef\semiChar = `\; -\chardef\spaceChar = `\ % \chardef\underChar = `\_ +\chardef\spaceChar = `\ % +\chardef\spacecat = 10 +\def\spaceisspace{\catcode\spaceChar=\spacecat} + % Ignore a token. % \def\gobble#1{} -% True if #1 is the empty string, i.e., called like `\ifempty{}'. -% -\def\ifempty#1{\ifemptyx #1\emptymarkA\emptymarkB}% -\def\ifemptyx#1#2\emptymarkB{\ifx #1\emptymarkA}% +% The following is used inside several \edef's. +\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname} % Hyphenation fixes. \hyphenation{ap-pen-dix} @@ -176,6 +184,41 @@ \newdimen\normaloffset \newdimen\pagewidth \newdimen\pageheight +% For a final copy, take out the rectangles +% that mark overfull boxes (in case you have decided +% that the text looks ok even though it passes the margin). +% +\def\finalout{\overfullrule=0pt} + +% @| inserts a changebar to the left of the current line. It should +% surround any changed text. This approach does *not* work if the +% change spans more than two lines of output. To handle that, we would +% have adopt a much more difficult approach (putting marks into the main +% vertical list for the beginning and end of each change). +% +\def\|{% + % \vadjust can only be used in horizontal mode. + \leavevmode + % + % Append this vertical mode material after the current line in the output. + \vadjust{% + % We want to insert a rule with the height and depth of the current + % leading; that is exactly what \strutbox is supposed to record. + \vskip-\baselineskip + % + % \vadjust-items are inserted at the left edge of the type. So + % the \llap here moves out into the left-hand margin. + \llap{% + % + % For a thicker or thinner bar, change the `1pt'. + \vrule height\baselineskip width1pt + % + % This is the space between the bar and the text. + \hskip 12pt + }% + }% +} + % Sometimes it is convenient to have everything in the transcript file % and nothing on the terminal. We don't just call \tracingall here, % since that produces some useless output on the terminal. We also make @@ -200,7 +243,7 @@ \tracingassigns1 \fi \tracingcommands3 % 3 gives us more in etex - \errorcontextlines\maxdimen + \errorcontextlines16 }% % add check for \lastpenalty to plain's definitions. If the last thing @@ -258,7 +301,7 @@ % the page break happens to be in the middle of an example. \shipout\vbox{% % Do this early so pdf references go to the beginning of the page. - \ifpdfmakepagedest \pdfmkdest{\the\pageno} \fi + \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi % \ifcropmarks \vbox to \outervsize\bgroup \hsize = \outerhsize @@ -339,132 +382,162 @@ % the input line (except we remove a trailing comment). #1 should be a % macro which expects an ordinary undelimited TeX argument. % -\def\parsearg#1{% - \let\next = #1% +\def\parsearg{\parseargusing{}} +\def\parseargusing#1#2{% + \def\next{#2}% \begingroup \obeylines - \futurelet\temp\parseargx -} - -% If the next token is an obeyed space (from an @example environment or -% the like), remove it and recurse. Otherwise, we're done. -\def\parseargx{% - % \obeyedspace is defined far below, after the definition of \sepspaces. - \ifx\obeyedspace\temp - \expandafter\parseargdiscardspace - \else - \expandafter\parseargline - \fi + \spaceisspace + #1% + \parseargline\empty% Insert the \empty token, see \finishparsearg below. } -% Remove a single space (as the delimiter token to the macro call). -{\obeyspaces % - \gdef\parseargdiscardspace {\futurelet\temp\parseargx}} - {\obeylines % \gdef\parseargline#1^^M{% \endgroup % End of the group started in \parsearg. - % - % First remove any @c comment, then any @comment. - % Result of each macro is put in \toks0. - \argremovec #1\c\relax % - \expandafter\argremovecomment \the\toks0 \comment\relax % - % - % Call the caller's macro, saved as \next in \parsearg. - \expandafter\next\expandafter{\the\toks0}% + \argremovecomment #1\comment\ArgTerm% }% } -% Since all \c{,omment} does is throw away the argument, we can let TeX -% do that for us. The \relax here is matched by the \relax in the call -% in \parseargline; it could be more or less anything, its purpose is -% just to delimit the argument to the \c. -\def\argremovec#1\c#2\relax{\toks0 = {#1}} -\def\argremovecomment#1\comment#2\relax{\toks0 = {#1}} +% First remove any @comment, then any @c comment. +\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm} +\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} -% \argremovec{,omment} might leave us with trailing spaces, though; e.g., +% Each occurence of `\^^M' or `<space>\^^M' is replaced by a single space. +% +% \argremovec might leave us with trailing space, e.g., % @end itemize @c foo -% will have two active spaces as part of the argument with the -% `itemize'. Here we remove all active spaces from #1, and assign the -% result to \toks0. -% -% This loses if there are any *other* active characters besides spaces -% in the argument -- _ ^ +, for example -- since they get expanded. -% Fortunately, Texinfo does not define any such commands. (If it ever -% does, the catcode of the characters in questionwill have to be changed -% here.) But this means we cannot call \removeactivespaces as part of -% \argremovec{,omment}, since @c uses \parsearg, and thus the argument -% that \parsearg gets might well have any character at all in it. -% -\def\removeactivespaces#1{% - \begingroup - \ignoreactivespaces - \edef\temp{#1}% - \global\toks0 = \expandafter{\temp}% - \endgroup +% This space token undergoes the same procedure and is eventually removed +% by \finishparsearg. +% +\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M} +\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M} +\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{% + \def\temp{#3}% + \ifx\temp\empty + % We cannot use \next here, as it holds the macro to run; + % thus we reuse \temp. + \let\temp\finishparsearg + \else + \let\temp\argcheckspaces + \fi + % Put the space token in: + \temp#1 #3\ArgTerm } -% Change the active space to expand to nothing. +% If a _delimited_ argument is enclosed in braces, they get stripped; so +% to get _exactly_ the rest of the line, we had to prevent such situation. +% We prepended an \empty token at the very beginning and we expand it now, +% just before passing the control to \next. +% (Similarily, we have to think about #3 of \argcheckspacesY above: it is +% either the null string, or it ends with \^^M---thus there is no danger +% that a pair of braces would be stripped. % -\begingroup - \obeyspaces - \gdef\ignoreactivespaces{\obeyspaces\let =\empty} -\endgroup +% But first, we have to remove the trailing space token. +% +\def\finishparsearg#1 \ArgTerm{\expandafter\next\expandafter{#1}} +% \parseargdef\foo{...} +% is roughly equivalent to +% \def\foo{\parsearg\Xfoo} +% \def\Xfoo#1{...} +% +% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my +% favourite TeX trick. --kasal, 16nov03 -\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} +\def\parseargdef#1{% + \expandafter \doparseargdef \csname\string#1\endcsname #1% +} +\def\doparseargdef#1#2{% + \def#2{\parsearg#1}% + \def#1##1% +} -%% These are used to keep @begin/@end levels from running away -%% Call \inENV within environments (after a \begingroup) -\newif\ifENV \ENVfalse \def\inENV{\ifENV\relax\else\ENVtrue\fi} -\def\ENVcheck{% -\ifENV\errmessage{Still within an environment; press RETURN to continue} -\endgroup\fi} % This is not perfect, but it should reduce lossage +% Several utility definitions with active space: +{ + \obeyspaces + \gdef\obeyedspace{ } -% @begin foo is the same as @foo, for now. -\newhelp\EMsimple{Press RETURN to continue.} + % Make each space character in the input produce a normal interword + % space in the output. Don't allow a line break at this space, as this + % is used only in environments like @example, where each line of input + % should produce a line of output anyway. + % + \gdef\sepspaces{\obeyspaces\let =\tie} -\outer\def\begin{\parsearg\beginxxx} + % If an index command is used in an @example environment, any spaces + % therein should become regular spaces in the raw index file, not the + % expansion of \tie (\leavevmode \penalty \@M \ ). + \gdef\unsepspaces{\let =\space} +} -\def\beginxxx #1{% -\expandafter\ifx\csname #1\endcsname\relax -{\errhelp=\EMsimple \errmessage{Undefined command @begin #1}}\else -\csname #1\endcsname\fi} -% @end foo executes the definition of \Efoo. -% -\def\end{\parsearg\endxxx} -\def\endxxx #1{% - \removeactivespaces{#1}% - \edef\endthing{\the\toks0}% - % - \expandafter\ifx\csname E\endthing\endcsname\relax - \expandafter\ifx\csname \endthing\endcsname\relax - % There's no \foo, i.e., no ``environment'' foo. - \errhelp = \EMsimple - \errmessage{Undefined command `@end \endthing'}% - \else - \unmatchedenderror\endthing - \fi +\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} + +% Define the framework for environments in texinfo.tex. It's used like this: +% +% \envdef\foo{...} +% \def\Efoo{...} +% +% It's the responsibility of \envdef to insert \begingroup before the +% actual body; @end closes the group after calling \Efoo. \envdef also +% defines \thisenv, so the current environment is known; @end checks +% whether the environment name matches. The \checkenv macro can also be +% used to check whether the current environment is the one expected. +% +% Non-false conditionals (@iftex, @ifset) don't fit into this, so they +% are not treated as enviroments; they don't open a group. (The +% implementation of @end takes care not to call \endgroup in this +% special case.) + + +% At runtime, environments start with this: +\def\startenvironment#1{\begingroup\def\thisenv{#1}} +% initialize +\let\thisenv\empty + +% ... but they get defined via ``\envdef\foo{...}'': +\long\def\envdef#1#2{\def#1{\startenvironment#1#2}} +\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}} + +% Check whether we're in the right environment: +\def\checkenv#1{% + \def\temp{#1}% + \ifx\thisenv\temp \else - % Everything's ok; the right environment has been started. - \csname E\endthing\endcsname + \badenverr \fi } -% There is an environment #1, but it hasn't been started. Give an error. -% -\def\unmatchedenderror#1{% +% Evironment mismatch, #1 expected: +\def\badenverr{% \errhelp = \EMsimple - \errmessage{This `@end #1' doesn't have a matching `@#1'}% + \errmessage{This command can appear only \inenvironment\temp, + not \inenvironment\thisenv}% +} +\def\inenvironment#1{% + \ifx#1\empty + out of any environment% + \else + in environment \expandafter\string#1% + \fi } -% Define the control sequence \E#1 to give an unmatched @end error. +% @end foo executes the definition of \Efoo. +% But first, it executes a specialized version of \checkenv % -\def\defineunmatchedend#1{% - \expandafter\def\csname E#1\endcsname{\unmatchedenderror{#1}}% +\parseargdef\end{% + \if 1\csname iscond.#1\endcsname + \else + % The general wording of \badenverr may not be ideal, but... --kasal, 06nov03 + \expandafter\checkenv\csname#1\endcsname + \csname E#1\endcsname + \endgroup + \fi } +\newhelp\EMsimple{Press RETURN to continue.} + %% Simple single-character @ commands @@ -496,6 +569,9 @@ !gdef!rbraceatcmd[@}]% !endgroup +% @comma{} to avoid , parsing problems. +\let\comma = , + % Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent % Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H. \let\, = \c @@ -505,10 +581,12 @@ \let\ubaraccent = \b \let\udotaccent = \d -% Other special characters: @questiondown @exclamdown +% Other special characters: @questiondown @exclamdown @ordf @ordm % Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. \def\questiondown{?`} \def\exclamdown{!`} +\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}} +\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}} % Dotless i and dotless j, used for accents. \def\imacro{i} @@ -521,6 +599,20 @@ \fi\fi } +% @LaTeX{} logo. (@TeX{} is defined in plain.tex.) +% Not quite the same results as the definition in latex.ltx, since we +% use a different font for the raised A; it's most convenient for us to +% go two sizes down, rather than using the \scriptstyle font (since we +% don't reset \scriptstyle and \scriptscriptstyle). +% +\def\LaTeX{% + L\kern-.36em + {\setbox0=\hbox{T}% + \vbox to \ht0{\hbox{\selectfonts\lllsize A}\vss}}% + \kern-.15em + \TeX +} + % Be sure we're in horizontal mode when doing a tie, since we make space % equivalent to this in @example-like environments. Otherwise, a space % at the beginning of a line will start with \penalty -- and @@ -574,59 +666,14 @@ \newbox\groupbox \def\vfilllimit{0.7} % -\def\group{\begingroup - \ifnum\catcode13=\active \else +\envdef\group{% + \ifnum\catcode`\^^M=\active \else \errhelp = \groupinvalidhelp \errmessage{@group invalid in context where filling is enabled}% \fi - % - % The \vtop we start below produces a box with normal height and large - % depth; thus, TeX puts \baselineskip glue before it, and (when the - % next line of text is done) \lineskip glue after it. (See p.82 of - % the TeXbook.) Thus, space below is not quite equal to space - % above. But it's pretty close. - \def\Egroup{% - \egroup % End the \vtop. - % \dimen0 is the vertical size of the group's box. - \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox - % \dimen2 is how much space is left on the page (more or less). - \dimen2 = \pageheight \advance\dimen2 by -\pagetotal - % if the group doesn't fit on the current page, and it's a big big - % group, force a page break. - \ifdim \dimen0 > \dimen2 - \ifdim \pagetotal < \vfilllimit\pageheight - \page - \fi - \fi - \copy\groupbox - \endgroup % End the \group. - }% + \startsavinginserts % \setbox\groupbox = \vtop\bgroup - % We have to put a strut on the last line in case the @group is in - % the midst of an example, rather than completely enclosing it. - % Otherwise, the interline space between the last line of the group - % and the first line afterwards is too small. But we can't put the - % strut in \Egroup, since there it would be on a line by itself. - % Hence this just inserts a strut at the beginning of each line. - \everypar = {\strut}% - % - % Since we have a strut on every line, we don't need any of TeX's - % normal interline spacing. - \offinterlineskip - % - % OK, but now we have to do something about blank - % lines in the input in @example-like environments, which normally - % just turn into \lisppar, which will insert no space now that we've - % turned off the interline space. Simplest is to make them be an - % empty paragraph. - \ifx\par\lisppar - \edef\par{\leavevmode \par}% - % - % Reset ^^M's definition to new definition of \par. - \obeylines - \fi - % % Do @comment since we are called inside an environment such as % @example, where each end-of-line in the input causes an % end-of-line in the output. We don't want the end-of-line after @@ -636,6 +683,32 @@ \comment } % +% The \vtop produces a box with normal height and large depth; thus, TeX puts +% \baselineskip glue before it, and (when the next line of text is done) +% \lineskip glue after it. Thus, space below is not quite equal to space +% above. But it's pretty close. +\def\Egroup{% + % To get correct interline space between the last line of the group + % and the first line afterwards, we have to propagate \prevdepth. + \endgraf % Not \par, as it may have been set to \lisppar. + \global\dimen1 = \prevdepth + \egroup % End the \vtop. + % \dimen0 is the vertical size of the group's box. + \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox + % \dimen2 is how much space is left on the page (more or less). + \dimen2 = \pageheight \advance\dimen2 by -\pagetotal + % if the group doesn't fit on the current page, and it's a big big + % group, force a page break. + \ifdim \dimen0 > \dimen2 + \ifdim \pagetotal < \vfilllimit\pageheight + \page + \fi + \fi + \box\groupbox + \prevdepth = \dimen1 + \checkinserts +} +% % TeX puts in an \escapechar (i.e., `@') at the beginning of the help % message, so this ends up printing `@group can only ...'. % @@ -648,10 +721,8 @@ where each line of input produces a line of output.} \newdimen\mil \mil=0.001in -\def\need{\parsearg\needx} - % Old definition--didn't work. -%\def\needx #1{\par % +%\parseargdef\need{\par % %% This method tries to make TeX break the page naturally %% if the depth of the box does not fit. %{\baselineskip=0pt% @@ -659,7 +730,7 @@ where each line of input produces a line of output.} %\prevdepth=-1000pt %}} -\def\needx#1{% +\parseargdef\need{% % Ensure vertical mode, so we don't make a big box in the middle of a % paragraph. \par @@ -698,35 +769,10 @@ where each line of input produces a line of output.} \fi } -% @br forces paragraph break +% @br forces paragraph break (and is undocumented). \let\br = \par -% @dots{} output an ellipsis using the current font. -% We do .5em per period so that it has the same spacing in a typewriter -% font as three actual period characters. -% -\def\dots{% - \leavevmode - \hbox to 1.5em{% - \hskip 0pt plus 0.25fil minus 0.25fil - .\hss.\hss.% - \hskip 0pt plus 0.5fil minus 0.5fil - }% -} - -% @enddots{} is an end-of-sentence ellipsis. -% -\def\enddots{% - \leavevmode - \hbox to 2em{% - \hskip 0pt plus 0.25fil minus 0.25fil - .\hss.\hss.\hss.% - \hskip 0pt plus 0.5fil minus 0.5fil - }% - \spacefactor=3000 -} - % @page forces the start of a new page. % \def\page{\par\vfill\supereject} @@ -739,13 +785,11 @@ where each line of input produces a line of output.} \newskip\exdentamount % This defn is used inside fill environments such as @defun. -\def\exdent{\parsearg\exdentyyy} -\def\exdentyyy #1{{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}} +\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break} % This defn is used inside nofill environments such as @example. -\def\nofillexdent{\parsearg\nofillexdentyyy} -\def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount -\leftline{\hskip\leftskip{\rm#1}}}} +\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount + \leftline{\hskip\leftskip{\rm#1}}}} % @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current % paragraph. For more general purposes, use the \margin insertion @@ -797,8 +841,19 @@ where each line of input produces a line of output.} } % @include file insert text of that file as input. -% Allow normal characters that we make active in the argument (a file name). -\def\include{\begingroup +% +\def\include{\parseargusing\filenamecatcodes\includezzz} +\def\includezzz#1{% + \pushthisfilestack + \def\thisfile{#1}% + {% + \makevalueexpandable + \def\temp{\input #1 }% + \expandafter + }\temp + \popthisfilestack +} +\def\filenamecatcodes{% \catcode`\\=\other \catcode`~=\other \catcode`^=\other @@ -807,33 +862,50 @@ where each line of input produces a line of output.} \catcode`<=\other \catcode`>=\other \catcode`+=\other - \parsearg\includezzz} -% Restore active chars for included file. -\def\includezzz#1{\endgroup\begingroup - % Read the included file in a group so nested @include's work. - \def\thisfile{#1}% - \let\value=\expandablevalue - \input\thisfile -\endgroup} + \catcode`-=\other +} + +\def\pushthisfilestack{% + \expandafter\pushthisfilestackX\popthisfilestack\StackTerm +} +\def\pushthisfilestackX{% + \expandafter\pushthisfilestackY\thisfile\StackTerm +} +\def\pushthisfilestackY #1\StackTerm #2\StackTerm {% + \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}% +} + +\def\popthisfilestack{\errthisfilestackempty} +\def\errthisfilestackempty{\errmessage{Internal error: + the stack of filenames is empty.}} \def\thisfile{} % @center line % outputs that line, centered. % -\def\center{\parsearg\docenter} -\def\docenter#1{{% - \ifhmode \hfil\break \fi - \advance\hsize by -\leftskip - \advance\hsize by -\rightskip - \line{\hfil \ignorespaces#1\unskip \hfil}% - \ifhmode \break \fi -}} +\parseargdef\center{% + \ifhmode + \let\next\centerH + \else + \let\next\centerV + \fi + \next{\hfil \ignorespaces#1\unskip \hfil}% +} +\def\centerH#1{% + {% + \hfil\break + \advance\hsize by -\leftskip + \advance\hsize by -\rightskip + \line{#1}% + \break + }% +} +\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}} % @sp n outputs n lines of vertical space -\def\sp{\parsearg\spxxx} -\def\spxxx #1{\vskip #1\baselineskip} +\parseargdef\sp{\vskip #1\baselineskip} % @comment ...line which is ignored... % @c is the same as @comment @@ -854,8 +926,7 @@ where each line of input produces a line of output.} \def\asisword{asis} % no translation, these are keywords \def\noneword{none} % -\def\paragraphindent{\parsearg\doparagraphindent} -\def\doparagraphindent#1{% +\parseargdef\paragraphindent{% \def\temp{#1}% \ifx\temp\asisword \else @@ -872,8 +943,7 @@ where each line of input produces a line of output.} % We'll use ems for NCHARS like @paragraphindent. % It seems @exampleindent asis isn't necessary, but % I preserve it to make it similar to @paragraphindent. -\def\exampleindent{\parsearg\doexampleindent} -\def\doexampleindent#1{% +\parseargdef\exampleindent{% \def\temp{#1}% \ifx\temp\asisword \else @@ -887,21 +957,20 @@ where each line of input produces a line of output.} % @firstparagraphindent WORD % If WORD is `none', then suppress indentation of the first paragraph -% after a section heading. If WORD is `insert', then do indentat such +% after a section heading. If WORD is `insert', then do indent at such % paragraphs. % % The paragraph indentation is suppressed or not by calling -% \suppressfirstparagraphindent, which the sectioning commands do. We -% switch the definition of this back and forth according to WORD. By -% default, we suppress indentation. +% \suppressfirstparagraphindent, which the sectioning commands do. +% We switch the definition of this back and forth according to WORD. +% By default, we suppress indentation. % \def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent} \newdimen\currentparindent % \def\insertword{insert} % -\def\firstparagraphindent{\parsearg\dofirstparagraphindent} -\def\dofirstparagraphindent#1{% +\parseargdef\firstparagraphindent{% \def\temp{#1}% \ifx\temp\noneword \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent @@ -921,15 +990,24 @@ where each line of input produces a line of output.} % \gdef\dosuppressfirstparagraphindent{% \gdef\indent{% - \global\let\indent=\ptexindent - \global\everypar = {}% + \restorefirstparagraphindent + \indent + }% + \gdef\noindent{% + \restorefirstparagraphindent + \noindent }% \global\everypar = {% - \kern-\parindent - \global\let\indent=\ptexindent - \global\everypar = {}% + \kern -\parindent + \restorefirstparagraphindent }% -}% +} + +\gdef\restorefirstparagraphindent{% + \global \let \indent = \ptexindent + \global \let \noindent = \ptexnoindent + \global \everypar = {}% +} % @asis just yields its argument. Used with @table, for example. @@ -937,23 +1015,18 @@ where each line of input produces a line of output.} \def\asis#1{#1} % @math outputs its argument in math mode. -% We don't use $'s directly in the definition of \math because we need -% to set catcodes according to plain TeX first, to allow for subscripts, -% superscripts, special math chars, etc. -% -\let\implicitmath = $%$ font-lock fix % % One complication: _ usually means subscripts, but it could also mean % an actual _ character, as in @math{@var{some_variable} + 1}. So make -% _ within @math be active (mathcode "8000), and distinguish by seeing -% if the current family is \slfam, which is what @var uses. -% -{\catcode\underChar = \active -\gdef\mathunderscore{% - \catcode\underChar=\active - \def_{\ifnum\fam=\slfam \_\else\sb\fi}% -}} -% +% _ active, and distinguish by seeing if the current family is \slfam, +% which is what @var uses. +{ + \catcode\underChar = \active + \gdef\mathunderscore{% + \catcode\underChar=\active + \def_{\ifnum\fam=\slfam \_\else\sb\fi}% + } +} % Another complication: we want \\ (and @\) to output a \ character. % FYI, plain.tex uses \\ as a temporary control sequence (why?), but % this is not advertised and we don't care. Texinfo does not @@ -964,15 +1037,16 @@ where each line of input produces a line of output.} % \def\math{% \tex - \mathcode`\_="8000 \mathunderscore + \mathunderscore \let\\ = \mathbackslash \mathactive - \implicitmath\finishmath} -\def\finishmath#1{#1\implicitmath\Etex} + $\finishmath +} +\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. % Some active characters (such as <) are spaced differently in math. -% We have to reset their definitions in case the @math was an -% argument to a command which set the catcodes (such as @item or @section). +% We have to reset their definitions in case the @math was an argument +% to a command which sets the catcodes (such as @item or @section). % { \catcode`^ = \active @@ -988,8 +1062,33 @@ where each line of input produces a line of output.} } % @bullet and @minus need the same treatment as @math, just above. -\def\bullet{\implicitmath\ptexbullet\implicitmath} -\def\minus{\implicitmath-\implicitmath} +\def\bullet{$\ptexbullet$} +\def\minus{$-$} + +% @dots{} outputs an ellipsis using the current font. +% We do .5em per period so that it has the same spacing in a typewriter +% font as three actual period characters. +% +\def\dots{% + \leavevmode + \hbox to 1.5em{% + \hskip 0pt plus 0.25fil + .\hfil.\hfil.% + \hskip 0pt plus 0.5fil + }% +} + +% @enddots{} is an end-of-sentence ellipsis. +% +\def\enddots{% + \dots + \spacefactor=3000 +} + +% @comma{} is so commas can be inserted into text without messing up +% Texinfo's parsing. +% +\let\comma = , % @refill is a no-op. \let\refill=\relax @@ -1006,7 +1105,9 @@ where each line of input produces a line of output.} % This makes it possible to make a .fmt file for texinfo. \def\setfilename{% \iflinks - \readauxfile + \tryauxfile + % Open the new aux file. TeX will close it automatically at exit. + \immediate\openout\auxfile=\jobname.aux \fi % \openindices needs to do some work in any case. \openindices \fixbackslash % Turn off hack to swallow `\input texinfo'. @@ -1014,11 +1115,9 @@ where each line of input produces a line of output.} % % If texinfo.cnf is present on the system, read it. % Useful for site-wide @afourpaper, etc. - % Just to be on the safe side, close the input stream before the \input. \openin 1 texinfo.cnf - \ifeof1 \let\temp=\relax \else \def\temp{\input texinfo.cnf }\fi - \closein1 - \temp + \ifeof 1 \else \input texinfo.cnf \fi + \closein 1 % \comment % Ignore the actual filename. } @@ -1065,6 +1164,7 @@ where each line of input produces a line of output.} \pdftrue \pdfoutput = 1 \input pdfcolor + \pdfcatalog{/PageMode /UseOutlines}% \def\dopdfimage#1#2#3{% \def\imagewidth{#2}% \def\imageheight{#3}% @@ -1085,7 +1185,13 @@ where each line of input produces a line of output.} \ifnum\pdftexversion < 14 \else \pdfrefximage \pdflastximage \fi} - \def\pdfmkdest#1{{\normalturnoffactive \pdfdest name{#1} xyz}} + \def\pdfmkdest#1{{% + % We have to set dummies so commands such as @code in a section title + % aren't expanded. + \atdummies + \normalturnoffactive + \pdfdest name{#1} xyz% + }} \def\pdfmkpgn#1{#1} \let\linkcolor = \Blue % was Cyan, but that seems light? \def\endlink{\Black\pdfendlink} @@ -1094,48 +1200,86 @@ where each line of input produces a line of output.} \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0% \else \csname#1\endcsname \fi} \def\advancenumber#1{\tempnum=\expnumber{#1}\relax - \advance\tempnum by1 + \advance\tempnum by 1 \expandafter\xdef\csname#1\endcsname{\the\tempnum}} - \def\pdfmakeoutlines{{% - \openin 1 \jobname.toc - \ifeof 1\else\begingroup - \closein 1 + % + % #1 is the section text. #2 is the pdf expression for the number + % of subentries (or empty, for subsubsections). #3 is the node + % text, which might be empty if this toc entry had no + % corresponding node. #4 is the page number. + % + \def\dopdfoutline#1#2#3#4{% + % Generate a link to the node text if that exists; else, use the + % page number. We could generate a destination for the section + % text in the case where a section has no node, but it doesn't + % seem worthwhile, since most documents are normally structured. + \def\pdfoutlinedest{#3}% + \ifx\pdfoutlinedest\empty \def\pdfoutlinedest{#4}\fi + % + \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{#1}% + } + % + \def\pdfmakeoutlines{% + \begingroup % Thanh's hack / proper braces in bookmarks \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace % - \def\chapentry ##1##2##3{} - \def\secentry ##1##2##3##4{\advancenumber{chap##2}} - \def\subsecentry ##1##2##3##4##5{\advancenumber{sec##2.##3}} - \def\subsubsecentry ##1##2##3##4##5##6{\advancenumber{subsec##2.##3.##4}} - \let\appendixentry = \chapentry - \let\unnumbchapentry = \chapentry - \let\unnumbsecentry = \secentry - \let\unnumbsubsecentry = \subsecentry - \let\unnumbsubsubsecentry = \subsubsecentry + % Read toc silently, to get counts of subentries for \pdfoutline. + \def\numchapentry##1##2##3##4{% + \def\thischapnum{##2}% + \let\thissecnum\empty + \let\thissubsecnum\empty + }% + \def\numsecentry##1##2##3##4{% + \advancenumber{chap\thischapnum}% + \def\thissecnum{##2}% + \let\thissubsecnum\empty + }% + \def\numsubsecentry##1##2##3##4{% + \advancenumber{sec\thissecnum}% + \def\thissubsecnum{##2}% + }% + \def\numsubsubsecentry##1##2##3##4{% + \advancenumber{subsec\thissubsecnum}% + }% + \let\thischapnum\empty + \let\thissecnum\empty + \let\thissubsecnum\empty + % + % use \def rather than \let here because we redefine \chapentry et + % al. a second time, below. + \def\appentry{\numchapentry}% + \def\appsecentry{\numsecentry}% + \def\appsubsecentry{\numsubsecentry}% + \def\appsubsubsecentry{\numsubsubsecentry}% + \def\unnchapentry{\numchapentry}% + \def\unnsecentry{\numsecentry}% + \def\unnsubsecentry{\numsubsecentry}% + \def\unnsubsubsecentry{\numsubsubsecentry}% \input \jobname.toc - \def\chapentry ##1##2##3{% - \pdfoutline goto name{\pdfmkpgn{##3}}count-\expnumber{chap##2}{##1}} - \def\secentry ##1##2##3##4{% - \pdfoutline goto name{\pdfmkpgn{##4}}count-\expnumber{sec##2.##3}{##1}} - \def\subsecentry ##1##2##3##4##5{% - \pdfoutline goto name{\pdfmkpgn{##5}}count-\expnumber{subsec##2.##3.##4}{##1}} - \def\subsubsecentry ##1##2##3##4##5##6{% - \pdfoutline goto name{\pdfmkpgn{##6}}{##1}} - \let\appendixentry = \chapentry - \let\unnumbchapentry = \chapentry - \let\unnumbsecentry = \secentry - \let\unnumbsubsecentry = \subsecentry - \let\unnumbsubsubsecentry = \subsubsecentry % - % Make special characters normal for writing to the pdf file. + % Read toc second time, this time actually producing the outlines. + % The `-' means take the \expnumber as the absolute number of + % subentries, which we calculated on our first read of the .toc above. + % + % We use the node names as the destinations. + \def\numchapentry##1##2##3##4{% + \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}% + \def\numsecentry##1##2##3##4{% + \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}% + \def\numsubsecentry##1##2##3##4{% + \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}% + \def\numsubsubsecentry##1##2##3##4{% count is always zero + \dopdfoutline{##1}{}{##3}{##4}}% % + % Make special characters normal for writing to the pdf file. \indexnofonts - \let\tt=\relax \turnoffactive \input \jobname.toc - \endgroup\fi - }} + \endgroup + } + % \def\makelinks #1,{% \def\params{#1}\def\E{END}% \ifx\params\E @@ -1184,7 +1328,7 @@ where each line of input produces a line of output.} \def\pdfurl#1{% \begingroup \normalturnoffactive\def\@{@}% - \let\value=\expandablevalue + \makevalueexpandable \leavevmode\Red \startlink attr{/Border [0 0 0]}% user{/Subtype /Link /A << /S /URI /URI (#1) >>}% @@ -1219,16 +1363,34 @@ where each line of input produces a line of output.} \message{fonts,} -% Font-change commands. + +% Change the current font style to #1, remembering it in \curfontstyle. +% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in +% italics, not bold italics. +% +\def\setfontstyle#1{% + \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd. + \csname ten#1\endcsname % change the current font +} + +% Select #1 fonts with the current style. +% +\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname} + +\def\rm{\fam=0 \setfontstyle{rm}} +\def\it{\fam=\itfam \setfontstyle{it}} +\def\sl{\fam=\slfam \setfontstyle{sl}} +\def\bf{\fam=\bffam \setfontstyle{bf}} +\def\tt{\fam=\ttfam \setfontstyle{tt}} % Texinfo sort of supports the sans serif font style, which plain TeX does not. -% So we set up a \sf analogous to plain's \rm, etc. +% So we set up a \sf. \newfam\sffam -\def\sf{\fam=\sffam \tensf} +\def\sf{\fam=\sffam \setfontstyle{sf}} \let\li = \sf % Sometimes we call it \li, not \sf. -% We don't need math for this one. -\def\ttsl{\tenttsl} +% We don't need math for this font style. +\def\ttsl{\setfontstyle{ttsl}} % Default leading. \newdimen\textleading \textleading = 13.2pt @@ -1279,6 +1441,7 @@ where each line of input produces a line of output.} \def\scshape{csc} \def\scbshape{csc} +% Text fonts (11.2pt, magstep1). \newcount\mainmagstep \ifx\bigger\relax % not really supported. @@ -1290,10 +1453,6 @@ where each line of input produces a line of output.} \setfont\textrm\rmshape{10}{\mainmagstep} \setfont\texttt\ttshape{10}{\mainmagstep} \fi -% Instead of cmb10, you may want to use cmbx10. -% cmbx10 is a prettier font on its own, but cmb10 -% looks better when embedded in a line with cmr10 -% (in Bob's opinion). \setfont\textbf\bfshape{10}{\mainmagstep} \setfont\textit\itshape{10}{\mainmagstep} \setfont\textsl\slshape{10}{\mainmagstep} @@ -1303,10 +1462,11 @@ where each line of input produces a line of output.} \font\texti=cmmi10 scaled \mainmagstep \font\textsy=cmsy10 scaled \mainmagstep -% A few fonts for @defun, etc. -\setfont\defbf\bxshape{10}{\magstep1} %was 1314 +% A few fonts for @defun names and args. +\setfont\defbf\bfshape{10}{\magstep1} \setfont\deftt\ttshape{10}{\magstep1} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} +\setfont\defttsl\ttslshape{10}{\magstep1} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} % Fonts for indices, footnotes, small examples (9pt). \setfont\smallrm\rmshape{9}{1000} @@ -1332,7 +1492,7 @@ where each line of input produces a line of output.} \font\smalleri=cmmi8 \font\smallersy=cmsy8 -% Fonts for title page: +% Fonts for title page (20.4pt): \setfont\titlerm\rmbshape{12}{\magstep3} \setfont\titleit\itbshape{10}{\magstep4} \setfont\titlesl\slbshape{10}{\magstep4} @@ -1378,11 +1538,21 @@ where each line of input produces a line of output.} \setfont\ssecttsl\ttslshape{10}{1315} \setfont\ssecsf\sfbshape{12}{\magstephalf} \let\ssecbf\ssecrm -\setfont\ssecsc\scbshape{10}{\magstep1} +\setfont\ssecsc\scbshape{10}{1315} \font\sseci=cmmi12 scaled \magstephalf \font\ssecsy=cmsy10 scaled 1315 -% The smallcaps and symbol fonts should actually be scaled \magstep1.5, -% but that is not a standard magnification. + +% Reduced fonts for @acro in text (10pt). +\setfont\reducedrm\rmshape{10}{1000} +\setfont\reducedtt\ttshape{10}{1000} +\setfont\reducedbf\bfshape{10}{1000} +\setfont\reducedit\itshape{10}{1000} +\setfont\reducedsl\slshape{10}{1000} +\setfont\reducedsf\sfshape{10}{1000} +\setfont\reducedsc\scshape{10}{1000} +\setfont\reducedttsl\ttslshape{10}{1000} +\font\reducedi=cmmi10 +\font\reducedsy=cmsy10 % In order for the font changes to affect most math symbols and letters, % we have to define the \textfont of the standard families. Since @@ -1397,50 +1567,72 @@ where each line of input produces a line of output.} } % The font-changing commands redefine the meanings of \tenSTYLE, instead -% of just \STYLE. We do this so that font changes will continue to work -% in math mode, where it is the current \fam that is relevant in most -% cases, not the current font. Plain TeX does \def\bf{\fam=\bffam -% \tenbf}, for example. By redefining \tenbf, we obviate the need to -% redefine \bf itself. +% of just \STYLE. We do this because \STYLE needs to also set the +% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire +% \tenSTYLE to set the current font. +% +% Each font-changing command also sets the names \lsize (one size lower) +% and \lllsize (three sizes lower). These relative commands are used in +% the LaTeX logo and acronyms. +% +% This all needs generalizing, badly. +% \def\textfonts{% \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc - \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy \let\tenttsl=\textttsl + \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy + \let\tenttsl=\textttsl + \def\lsize{reduced}\def\lllsize{smaller}% \resetmathfonts \setleading{\textleading}} \def\titlefonts{% \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy \let\tenttsl=\titlettsl + \def\lsize{chap}\def\lllsize{subsec}% \resetmathfonts \setleading{25pt}} \def\titlefont#1{{\titlefonts\rm #1}} \def\chapfonts{% \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy \let\tenttsl=\chapttsl + \def\lsize{sec}\def\lllsize{text}% \resetmathfonts \setleading{19pt}} \def\secfonts{% \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc - \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy \let\tenttsl=\secttsl + \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy + \let\tenttsl=\secttsl + \def\lsize{subsec}\def\lllsize{reduced}% \resetmathfonts \setleading{16pt}} \def\subsecfonts{% \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc - \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy \let\tenttsl=\ssecttsl + \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy + \let\tenttsl=\ssecttsl + \def\lsize{text}\def\lllsize{small}% \resetmathfonts \setleading{15pt}} -\let\subsubsecfonts = \subsecfonts % Maybe make sssec fonts scaled magstephalf? +\let\subsubsecfonts = \subsecfonts +\def\reducedfonts{% + \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl + \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc + \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy + \let\tenttsl=\reducedttsl + \def\lsize{small}\def\lllsize{smaller}% + \resetmathfonts \setleading{10.5pt}} \def\smallfonts{% \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy \let\tenttsl=\smallttsl + \def\lsize{smaller}\def\lllsize{smaller}% \resetmathfonts \setleading{10.5pt}} \def\smallerfonts{% \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy \let\tenttsl=\smallerttsl + \def\lsize{smaller}\def\lllsize{smaller}% \resetmathfonts \setleading{9.5pt}} % Set the fonts to use with the @small... environments. @@ -1449,7 +1641,7 @@ where each line of input produces a line of output.} % About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample % can fit this many characters: % 8.5x11=86 smallbook=72 a4=90 a5=69 -% If we use \smallerfonts (8pt), then we can fit this many characters: +% If we use \scriptfonts (8pt), then we can fit this many characters: % 8.5x11=90+ smallbook=80 a4=90+ a5=77 % For me, subjectively, the few extra characters that fit aren't worth % the additional smallness of 8pt. So I'm making the default 9pt. @@ -1457,14 +1649,13 @@ where each line of input produces a line of output.} % By the way, for comparison, here's what fits with @example (10pt): % 8.5x11=71 smallbook=60 a4=75 a5=58 % -% I wish we used A4 paper on this side of the Atlantic. -% +% I wish the USA used A4 paper. % --karl, 24jan03. % Set up the default fonts, so we can use them for creating boxes. % -\textfonts +\textfonts \rm % Define these so they can be easily changed for other fonts. \def\angleleft{$\langle$} @@ -1475,7 +1666,7 @@ where each line of input produces a line of output.} % Fonts for short table of contents. \setfont\shortcontrm\rmshape{12}{1000} -\setfont\shortcontbf\bxshape{12}{1000} +\setfont\shortcontbf\bfshape{10}{\magstep1} % no cmb12 \setfont\shortcontsl\slshape{12}{1000} \setfont\shortconttt\ttshape{12}{1000} @@ -1489,11 +1680,18 @@ where each line of input produces a line of output.} \def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx} \def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx} +% like \smartslanted except unconditionally uses \ttsl. +% @var is set to this for defun arguments. +\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx} + +% like \smartslanted except unconditionally use \sl. We never want +% ttsl for book titles, do we? +\def\cite#1{{\sl #1}\futurelet\next\smartitalicx} + \let\i=\smartitalic \let\var=\smartslanted \let\dfn=\smartslanted \let\emph=\smartitalic -\let\cite=\smartslanted \def\b#1{{\bf #1}} \let\strong=\b @@ -1520,7 +1718,6 @@ where each line of input produces a line of output.} {\tt \rawbackslash \frenchspacing #1}% \null } -\let\ttfont=\t \def\samp#1{`\tclose{#1}'\null} \setfont\keyrm\rmshape{8}{1000} \font\keysy=cmsy9 @@ -1561,7 +1758,7 @@ where each line of input produces a line of output.} \null } -% We *must* turn on hyphenation at `-' and `_' in \code. +% We *must* turn on hyphenation at `-' and `_' in @code. % Otherwise, it is too hard to avoid overfull hboxes % in the Emacs manual, the Library manual, etc. @@ -1579,10 +1776,6 @@ where each line of input produces a line of output.} \catcode`\_=\active \let_\codeunder \codex } - % - % If we end up with any active - characters when handling the index, - % just treat them as a normal -. - \global\def\indexbreaks{\catcode`\-=\active \let-\realdash} } \def\realdash{-} @@ -1606,8 +1799,7 @@ where each line of input produces a line of output.} % @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), % `example' (@kbd uses ttsl only inside of @example and friends), % or `code' (@kbd uses normal tty font always). -\def\kbdinputstyle{\parsearg\kbdinputstylexxx} -\def\kbdinputstylexxx#1{% +\parseargdef\kbdinputstyle{% \def\arg{#1}% \ifx\arg\worddistinct \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% @@ -1707,19 +1899,26 @@ where each line of input produces a line of output.} \def\sc#1{{\smallcaps#1}} % smallcaps font \def\ii#1{{\it #1}} % italic font -% @acronym downcases the argument and prints in smallcaps. -\def\acronym#1{{\smallcaps \lowercase{#1}}} +\def\acronym#1{\doacronym #1,,\finish} +\def\doacronym#1,#2,#3\finish{% + {\selectfonts\lsize #1}% + \def\temp{#2}% + \ifx\temp\empty \else + \space ({\unsepspaces \ignorespaces \temp \unskip})% + \fi +} -% @pounds{} is a sterling sign. +% @pounds{} is a sterling sign, which is in the CM italic font. +% \def\pounds{{\it\$}} -% @registeredsymbol - R in a circle. For now, only works in text size; -% we'd have to redo the font mechanism to change the \scriptstyle and -% \scriptscriptstyle font sizes to make it look right in headings. +% @registeredsymbol - R in a circle. The font for the R should really +% be smaller yet, but lllsize is the best we can do for now. % Adapted from the plain.tex definition of \copyright. % \def\registeredsymbol{% - $^{{\ooalign{\hfil\raise.07ex\hbox{$\scriptstyle\rm R$}\hfil\crcr\Orb}}% + $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}% + \hfil\crcr\Orb}}% }$% } @@ -1741,87 +1940,102 @@ where each line of input produces a line of output.} \newif\ifsetshortcontentsaftertitlepage \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue -\def\shorttitlepage{\parsearg\shorttitlepagezzz} -\def\shorttitlepagezzz #1{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% +\parseargdef\shorttitlepage{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% \endgroup\page\hbox{}\page} -\def\titlepage{\begingroup \parindent=0pt \textfonts - \let\subtitlerm=\tenrm - \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}% - % - \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines - \let\tt=\authortt}% - % - % Leave some space at the very top of the page. - \vglue\titlepagetopglue - % - % Now you can print the title using @title. - \def\title{\parsearg\titlezzz}% - \def\titlezzz##1{\leftline{\titlefonts\rm ##1} - % print a rule at the page bottom also. - \finishedtitlepagefalse - \vskip4pt \hrule height 4pt width \hsize \vskip4pt}% - % No rule at page bottom unless we print one at the top with @title. - \finishedtitlepagetrue - % - % Now you can put text using @subtitle. - \def\subtitle{\parsearg\subtitlezzz}% - \def\subtitlezzz##1{{\subtitlefont \rightline{##1}}}% - % - % @author should come last, but may come many times. - \def\author{\parsearg\authorzzz}% - \def\authorzzz##1{\ifseenauthor\else\vskip 0pt plus 1filll\seenauthortrue\fi - {\authorfont \leftline{##1}}}% - % - % Most title ``pages'' are actually two pages long, with space - % at the top of the second. We don't want the ragged left on the second. - \let\oldpage = \page - \def\page{% +\envdef\titlepage{% + % Open one extra group, as we want to close it in the middle of \Etitlepage. + \begingroup + \parindent=0pt \textfonts + % Leave some space at the very top of the page. + \vglue\titlepagetopglue + % No rule at page bottom unless we print one at the top with @title. + \finishedtitlepagetrue + % + % Most title ``pages'' are actually two pages long, with space + % at the top of the second. We don't want the ragged left on the second. + \let\oldpage = \page + \def\page{% \iffinishedtitlepage\else - \finishtitlepage + \finishtitlepage \fi - \oldpage \let\page = \oldpage - \hbox{}}% -% \def\page{\oldpage \hbox{}} + \page + \null + }% } \def\Etitlepage{% - \iffinishedtitlepage\else - \finishtitlepage - \fi - % It is important to do the page break before ending the group, - % because the headline and footline are only empty inside the group. - % If we use the new definition of \page, we always get a blank page - % after the title page, which we certainly don't want. - \oldpage - \endgroup - % - % Need this before the \...aftertitlepage checks so that if they are - % in effect the toc pages will come out with page numbers. - \HEADINGSon - % - % If they want short, they certainly want long too. - \ifsetshortcontentsaftertitlepage - \shortcontents - \contents - \global\let\shortcontents = \relax - \global\let\contents = \relax - \fi - % - \ifsetcontentsaftertitlepage - \contents - \global\let\contents = \relax - \global\let\shortcontents = \relax - \fi + \iffinishedtitlepage\else + \finishtitlepage + \fi + % It is important to do the page break before ending the group, + % because the headline and footline are only empty inside the group. + % If we use the new definition of \page, we always get a blank page + % after the title page, which we certainly don't want. + \oldpage + \endgroup + % + % Need this before the \...aftertitlepage checks so that if they are + % in effect the toc pages will come out with page numbers. + \HEADINGSon + % + % If they want short, they certainly want long too. + \ifsetshortcontentsaftertitlepage + \shortcontents + \contents + \global\let\shortcontents = \relax + \global\let\contents = \relax + \fi + % + \ifsetcontentsaftertitlepage + \contents + \global\let\contents = \relax + \global\let\shortcontents = \relax + \fi } \def\finishtitlepage{% - \vskip4pt \hrule height 2pt width \hsize - \vskip\titlepagebottomglue - \finishedtitlepagetrue + \vskip4pt \hrule height 2pt width \hsize + \vskip\titlepagebottomglue + \finishedtitlepagetrue } +%%% Macros to be used within @titlepage: + +\let\subtitlerm=\tenrm +\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines} + +\def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines + \let\tt=\authortt} + +\parseargdef\title{% + \checkenv\titlepage + \leftline{\titlefonts\rm #1} + % print a rule at the page bottom also. + \finishedtitlepagefalse + \vskip4pt \hrule height 4pt width \hsize \vskip4pt +} + +\parseargdef\subtitle{% + \checkenv\titlepage + {\subtitlefont \rightline{#1}}% +} + +% @author should come last, but may come many times. +\parseargdef\author{% + \def\temp{\quotation}% + \ifx\thisenv\temp + This edition of the manual is dedicated to Karl Berry who should + really make affiliations work. + \else + \checkenv\titlepage + \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi + {\authorfont \leftline{#1}}% + \fi +} + + %%% Set up page headings and footings. \let\thispage=\folio @@ -1831,7 +2045,7 @@ where each line of input produces a line of output.} \newtoks\evenfootline % footline on even pages \newtoks\oddfootline % footline on odd pages -% Now make Tex use those variables +% Now make TeX use those variables \headline={{\textfonts\rm \ifodd\pageno \the\oddheadline \else \the\evenheadline \fi}} \footline={{\textfonts\rm \ifodd\pageno \the\oddfootline @@ -1845,32 +2059,27 @@ where each line of input produces a line of output.} % @evenfooting @thisfile|| % @oddfooting ||@thisfile -\def\evenheading{\parsearg\evenheadingxxx} -\def\oddheading{\parsearg\oddheadingxxx} -\def\everyheading{\parsearg\everyheadingxxx} -\def\evenfooting{\parsearg\evenfootingxxx} -\def\oddfooting{\parsearg\oddfootingxxx} -\def\everyfooting{\parsearg\everyfootingxxx} - -{\catcode`\@=0 % - -\gdef\evenheadingxxx #1{\evenheadingyyy #1@|@|@|@|\finish} -\gdef\evenheadingyyy #1@|#2@|#3@|#4\finish{% +\def\evenheading{\parsearg\evenheadingxxx} +\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish} +\def\evenheadingyyy #1\|#2\|#3\|#4\finish{% \global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} -\gdef\oddheadingxxx #1{\oddheadingyyy #1@|@|@|@|\finish} -\gdef\oddheadingyyy #1@|#2@|#3@|#4\finish{% +\def\oddheading{\parsearg\oddheadingxxx} +\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish} +\def\oddheadingyyy #1\|#2\|#3\|#4\finish{% \global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} -\gdef\everyheadingxxx#1{\oddheadingxxx{#1}\evenheadingxxx{#1}}% +\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}% -\gdef\evenfootingxxx #1{\evenfootingyyy #1@|@|@|@|\finish} -\gdef\evenfootingyyy #1@|#2@|#3@|#4\finish{% +\def\evenfooting{\parsearg\evenfootingxxx} +\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish} +\def\evenfootingyyy #1\|#2\|#3\|#4\finish{% \global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} -\gdef\oddfootingxxx #1{\oddfootingyyy #1@|@|@|@|\finish} -\gdef\oddfootingyyy #1@|#2@|#3@|#4\finish{% +\def\oddfooting{\parsearg\oddfootingxxx} +\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish} +\def\oddfootingyyy #1\|#2\|#3\|#4\finish{% \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}% % % Leave some space for the footline. Hopefully ok to assume @@ -1879,9 +2088,8 @@ where each line of input produces a line of output.} \global\advance\vsize by -\baselineskip } -\gdef\everyfootingxxx#1{\oddfootingxxx{#1}\evenfootingxxx{#1}} -% -}% unbind the catcode of @. +\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}} + % @headings double turns headings on for double-sided printing. % @headings single turns headings on for single-sided printing. @@ -1895,7 +2103,7 @@ where each line of input produces a line of output.} \def\headings #1 {\csname HEADINGS#1\endcsname} -\def\HEADINGSoff{ +\def\HEADINGSoff{% \global\evenheadline={\hfil} \global\evenfootline={\hfil} \global\oddheadline={\hfil} \global\oddfootline={\hfil}} \HEADINGSoff @@ -1904,7 +2112,7 @@ where each line of input produces a line of output.} % chapter name on inside top of right hand pages, document % title on inside top of left hand pages, and page numbers on outside top % edge of all pages. -\def\HEADINGSdouble{ +\def\HEADINGSdouble{% \global\pageno=1 \global\evenfootline={\hfil} \global\oddfootline={\hfil} @@ -1916,7 +2124,7 @@ where each line of input produces a line of output.} % For single-sided printing, chapter title goes across top left of page, % page number on top right. -\def\HEADINGSsingle{ +\def\HEADINGSsingle{% \global\pageno=1 \global\evenfootline={\hfil} \global\oddfootline={\hfil} @@ -1963,12 +2171,11 @@ where each line of input produces a line of output.} % @settitle line... specifies the title of the document, for headings. % It generates no output of its own. \def\thistitle{\putwordNoTitle} -\def\settitle{\parsearg\settitlezzz} -\def\settitlezzz #1{\gdef\thistitle{#1}} +\def\settitle{\parsearg{\gdef\thistitle}} \message{tables,} -% Tables -- @table, @ftable, @vtable, @item(x), @kitem(x), @xitem(x). +% Tables -- @table, @ftable, @vtable, @item(x). % default indentation of table text \newdimen\tableindent \tableindent=.8in @@ -1980,7 +2187,7 @@ where each line of input produces a line of output.} % used internally for \itemindent minus \itemmargin \newdimen\itemmax -% Note @table, @vtable, and @vtable define @item, @itemx, etc., with +% Note @table, @ftable, and @vtable define @item, @itemx, etc., with % these defs. % They also define \itemindex % to index the item name in whatever manner is desired (perhaps none). @@ -1992,22 +2199,10 @@ where each line of input produces a line of output.} \def\internalBitem{\smallbreak \parsearg\itemzzz} \def\internalBitemx{\itemxpar \parsearg\itemzzz} -\def\internalBxitem "#1"{\def\xitemsubtopix{#1} \smallbreak \parsearg\xitemzzz} -\def\internalBxitemx "#1"{\def\xitemsubtopix{#1} \itemxpar \parsearg\xitemzzz} - -\def\internalBkitem{\smallbreak \parsearg\kitemzzz} -\def\internalBkitemx{\itemxpar \parsearg\kitemzzz} - -\def\kitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \lastfunction}}% - \itemzzz {#1}} - -\def\xitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \xitemsubtopic}}% - \itemzzz {#1}} - \def\itemzzz #1{\begingroup % \advance\hsize by -\rightskip \advance\hsize by -\tableindent - \setbox0=\hbox{\itemfont{#1}}% + \setbox0=\hbox{\itemindicate{#1}}% \itemindex{#1}% \nobreak % This prevents a break before @itemx. % @@ -2061,81 +2256,63 @@ where each line of input produces a line of output.} \fi } -\def\item{\errmessage{@item while not in a table}} -\def\itemx{\errmessage{@itemx while not in a table}} -\def\kitem{\errmessage{@kitem while not in a table}} -\def\kitemx{\errmessage{@kitemx while not in a table}} -\def\xitem{\errmessage{@xitem while not in a table}} -\def\xitemx{\errmessage{@xitemx while not in a table}} - -% Contains a kludge to get @end[description] to work. -\def\description{\tablez{\dontindex}{1}{}{}{}{}} +\def\item{\errmessage{@item while not in a list environment}} +\def\itemx{\errmessage{@itemx while not in a list environment}} % @table, @ftable, @vtable. -\def\table{\begingroup\inENV\obeylines\obeyspaces\tablex} -{\obeylines\obeyspaces% -\gdef\tablex #1^^M{% -\tabley\dontindex#1 \endtabley}} - -\def\ftable{\begingroup\inENV\obeylines\obeyspaces\ftablex} -{\obeylines\obeyspaces% -\gdef\ftablex #1^^M{% -\tabley\fnitemindex#1 \endtabley -\def\Eftable{\endgraf\afterenvbreak\endgroup}% -\let\Etable=\relax}} - -\def\vtable{\begingroup\inENV\obeylines\obeyspaces\vtablex} -{\obeylines\obeyspaces% -\gdef\vtablex #1^^M{% -\tabley\vritemindex#1 \endtabley -\def\Evtable{\endgraf\afterenvbreak\endgroup}% -\let\Etable=\relax}} - -\def\dontindex #1{} -\def\fnitemindex #1{\doind {fn}{\code{#1}}}% -\def\vritemindex #1{\doind {vr}{\code{#1}}}% - -{\obeyspaces % -\gdef\tabley#1#2 #3 #4 #5 #6 #7\endtabley{\endgroup% -\tablez{#1}{#2}{#3}{#4}{#5}{#6}}} - -\def\tablez #1#2#3#4#5#6{% -\aboveenvbreak % -\begingroup % -\def\Edescription{\Etable}% Necessary kludge. -\let\itemindex=#1% -\ifnum 0#3>0 \advance \leftskip by #3\mil \fi % -\ifnum 0#4>0 \tableindent=#4\mil \fi % -\ifnum 0#5>0 \advance \rightskip by #5\mil \fi % -\def\itemfont{#2}% -\itemmax=\tableindent % -\advance \itemmax by -\itemmargin % -\advance \leftskip by \tableindent % -\exdentamount=\tableindent -\parindent = 0pt -\parskip = \smallskipamount -\ifdim \parskip=0pt \parskip=2pt \fi% -\def\Etable{\endgraf\afterenvbreak\endgroup}% -\let\item = \internalBitem % -\let\itemx = \internalBitemx % -\let\kitem = \internalBkitem % -\let\kitemx = \internalBkitemx % -\let\xitem = \internalBxitem % -\let\xitemx = \internalBxitemx % +\envdef\table{% + \let\itemindex\gobble + \tablex +} +\envdef\ftable{% + \def\itemindex ##1{\doind {fn}{\code{##1}}}% + \tablex +} +\envdef\vtable{% + \def\itemindex ##1{\doind {vr}{\code{##1}}}% + \tablex +} +\def\tablex#1{% + \def\itemindicate{#1}% + \parsearg\tabley +} +\def\tabley#1{% + {% + \makevalueexpandable + \edef\temp{\noexpand\tablez #1\space\space\space}% + \expandafter + }\temp \endtablez } +\def\tablez #1 #2 #3 #4\endtablez{% + \aboveenvbreak + \ifnum 0#1>0 \advance \leftskip by #1\mil \fi + \ifnum 0#2>0 \tableindent=#2\mil \fi + \ifnum 0#3>0 \advance \rightskip by #3\mil \fi + \itemmax=\tableindent + \advance \itemmax by -\itemmargin + \advance \leftskip by \tableindent + \exdentamount=\tableindent + \parindent = 0pt + \parskip = \smallskipamount + \ifdim \parskip=0pt \parskip=2pt \fi + \let\item = \internalBitem + \let\itemx = \internalBitemx +} +\def\Etable{\endgraf\afterenvbreak} +\let\Eftable\Etable +\let\Evtable\Etable +\let\Eitemize\Etable +\let\Eenumerate\Etable % This is the counter used by @enumerate, which is really @itemize \newcount \itemno -\def\itemize{\parsearg\itemizezzz} - -\def\itemizezzz #1{% - \begingroup % ended by the @end itemize - \itemizey {#1}{\Eitemize} +\envdef\itemize{% + \parsearg\itemizey } -\def\itemizey#1#2{% +\def\itemizey#1{% \aboveenvbreak \itemmax=\itemindent \advance\itemmax by -\itemmargin @@ -2144,7 +2321,6 @@ where each line of input produces a line of output.} \parindent=0pt \parskip=\smallskipamount \ifdim\parskip=0pt \parskip=2pt \fi - \def#2{\endgraf\afterenvbreak\endgroup}% \def\itemcontents{#1}% % @itemize with no arg is equivalent to @itemize @bullet. \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi @@ -2160,11 +2336,8 @@ where each line of input produces a line of output.} % or number, to specify the first label in the enumerated list. No % argument is the same as `1'. % -\def\enumerate{\parsearg\enumeratezzz} -\def\enumeratezzz #1{\enumeratey #1 \endenumeratey} +\envparseargdef\enumerate{\enumeratey #1 \endenumeratey} \def\enumeratey #1 #2\endenumeratey{% - \begingroup % ended by the @end enumerate - % % If we were given no argument, pretend we were given `1'. \def\thearg{#1}% \ifx\thearg\empty \def\thearg{1}\fi @@ -2241,7 +2414,7 @@ where each line of input produces a line of output.} % \def\startenumeration#1{% \advance\itemno by -1 - \itemizey{#1.}\Eenumerate\flushcr + \itemizey{#1.}\flushcr } % @alphaenumerate and @capsenumerate are abbreviations for giving an arg @@ -2288,24 +2461,14 @@ where each line of input produces a line of output.} % @multitable {Column 1 template} {Column 2 template} {Column 3 template} % @item ... % using the widest term desired in each column. -% -% For those who want to use more than one line's worth of words in -% the preamble, break the line within one argument and it -% will parse correctly, i.e., -% -% @multitable {Column 1 template} {Column 2 template} {Column 3 -% template} -% Not: -% @multitable {Column 1 template} {Column 2 template} -% {Column 3 template} % Each new table line starts with @item, each subsequent new column % starts with @tab. Empty columns may be produced by supplying @tab's % with nothing between them for as many times as empty columns are needed, % ie, @tab@tab@tab will produce two empty columns. -% @item, @tab, @multitable or @end multitable do not need to be on their -% own lines, but it will not hurt if they are. +% @item, @tab do not need to be on their own lines, but it will not hurt +% if they are. % Sample multitable: @@ -2388,18 +2551,30 @@ where each line of input produces a line of output.} \go } +% multitable-only commands. +% +% @headitem starts a heading row, which we typeset in bold. +% Assignments have to be global since we are inside the implicit group +% of an alignment entry. Note that \everycr resets \everytab. +\def\headitem{\checkenv\multitable \crcr \global\everytab={\bf}\the\everytab}% +% +% A \tab used to include \hskip1sp. But then the space in a template +% line is not enough. That is bad. So let's go back to just `&' until +% we encounter the problem it was intended to solve again. +% --karl, nathan@acm.org, 20apr99. +\def\tab{\checkenv\multitable &\the\everytab}% + % @multitable ... @end multitable definitions: % -\def\multitable{\parsearg\dotable} -\def\dotable#1{\bgroup +\newtoks\everytab % insert after every tab. +% +\envdef\multitable{% \vskip\parskip - \let\item=\crcrwithfootnotes - % A \tab used to include \hskip1sp. But then the space in a template - % line is not enough. That is bad. So let's go back to just & until - % we encounter the problem it was intended to solve again. --karl, - % nathan@acm.org, 20apr99. - \let\tab=&% - \let\startfootins=\startsavedfootnote + \startsavinginserts + % + % @item within a multitable starts a normal row. + \let\item\crcr + % \tolerance=9500 \hbadness=9500 \setmultitablespacing @@ -2407,70 +2582,80 @@ where each line of input produces a line of output.} \parindent=\multitableparindent \overfullrule=0pt \global\colcount=0 - \def\Emultitable{% - \global\setpercentfalse - \crcrwithfootnotes\crcr - \egroup\egroup + % + \everycr = {% + \noalign{% + \global\everytab={}% + \global\colcount=0 % Reset the column counter. + % Check for saved footnotes, etc. + \checkinserts + % Keeps underfull box messages off when table breaks over pages. + %\filbreak + % Maybe so, but it also creates really weird page breaks when the + % table breaks over pages. Wouldn't \vfil be better? Wait until the + % problem manifests itself, so it can be fixed for real --karl. + }% }% % + \parsearg\domultitable +} +\def\domultitable#1{% % To parse everything between @multitable and @item: \setuptable#1 \endsetuptable % - % \everycr will reset column counter, \colcount, at the end of - % each line. Every column entry will cause \colcount to advance by one. - % The table preamble - % looks at the current \colcount to find the correct column width. - \everycr{\noalign{% - % - % \filbreak%% keeps underfull box messages off when table breaks over pages. - % Maybe so, but it also creates really weird page breaks when the table - % breaks over pages. Wouldn't \vfil be better? Wait until the problem - % manifests itself, so it can be fixed for real --karl. - \global\colcount=0\relax}}% - % % This preamble sets up a generic column definition, which will % be used as many times as user calls for columns. % \vtop will set a single line and will also let text wrap and % continue for many paragraphs if desired. - \halign\bgroup&\global\advance\colcount by 1\relax - \multistrut\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname - % - % In order to keep entries from bumping into each other - % we will add a \leftskip of \multitablecolspace to all columns after - % the first one. - % - % If a template has been used, we will add \multitablecolspace - % to the width of each template entry. - % - % If the user has set preamble in terms of percent of \hsize we will - % use that dimension as the width of the column, and the \leftskip - % will keep entries from bumping into each other. Table will start at - % left margin and final column will justify at right margin. - % - % Make sure we don't inherit \rightskip from the outer environment. - \rightskip=0pt - \ifnum\colcount=1 - % The first column will be indented with the surrounding text. - \advance\hsize by\leftskip - \else - \ifsetpercent \else - % If user has not set preamble in terms of percent of \hsize - % we will advance \hsize by \multitablecolspace. - \advance\hsize by \multitablecolspace - \fi - % In either case we will make \leftskip=\multitablecolspace: - \leftskip=\multitablecolspace - \fi - % Ignoring space at the beginning and end avoids an occasional spurious - % blank line, when TeX decides to break the line at the space before the - % box from the multistrut, so the strut ends up on a line by itself. - % For example: - % @multitable @columnfractions .11 .89 - % @item @code{#} - % @tab Legal holiday which is valid in major parts of the whole country. - % Is automatically provided with highlighting sequences respectively marking - % characters. - \noindent\ignorespaces##\unskip\multistrut}\cr + \halign\bgroup &% + \global\advance\colcount by 1 + \multistrut + \vtop{% + % Use the current \colcount to find the correct column width: + \hsize=\expandafter\csname col\the\colcount\endcsname + % + % In order to keep entries from bumping into each other + % we will add a \leftskip of \multitablecolspace to all columns after + % the first one. + % + % If a template has been used, we will add \multitablecolspace + % to the width of each template entry. + % + % If the user has set preamble in terms of percent of \hsize we will + % use that dimension as the width of the column, and the \leftskip + % will keep entries from bumping into each other. Table will start at + % left margin and final column will justify at right margin. + % + % Make sure we don't inherit \rightskip from the outer environment. + \rightskip=0pt + \ifnum\colcount=1 + % The first column will be indented with the surrounding text. + \advance\hsize by\leftskip + \else + \ifsetpercent \else + % If user has not set preamble in terms of percent of \hsize + % we will advance \hsize by \multitablecolspace. + \advance\hsize by \multitablecolspace + \fi + % In either case we will make \leftskip=\multitablecolspace: + \leftskip=\multitablecolspace + \fi + % Ignoring space at the beginning and end avoids an occasional spurious + % blank line, when TeX decides to break the line at the space before the + % box from the multistrut, so the strut ends up on a line by itself. + % For example: + % @multitable @columnfractions .11 .89 + % @item @code{#} + % @tab Legal holiday which is valid in major parts of the whole country. + % Is automatically provided with highlighting sequences respectively + % marking characters. + \noindent\ignorespaces##\unskip\multistrut + }\cr +} +\def\Emultitable{% + \crcr + \egroup % end the \halign + \global\setpercentfalse } \def\setmultitablespacing{% test to see if user has set \multitablelinespace. @@ -2500,163 +2685,33 @@ width0pt\relax} \fi %% than skip between lines in the table. \fi} -% In case a @footnote appears inside an alignment, save the footnote -% text to a box and make the \insert when a row of the table is -% finished. Otherwise, the insertion is lost, it never migrates to the -% main vertical list. --kasal, 22jan03. -% -\newbox\savedfootnotes -% -% \dotable \let's \startfootins to this, so that \dofootnote will call -% it instead of starting the insertion right away. -\def\startsavedfootnote{% - \global\setbox\savedfootnotes = \vbox\bgroup - \unvbox\savedfootnotes -} -\def\crcrwithfootnotes{% - \crcr - \ifvoid\savedfootnotes \else - \noalign{\insert\footins{\box\savedfootnotes}}% - \fi -} \message{conditionals,} -% Prevent errors for section commands. -% Used in @ignore and in failing conditionals. -\def\ignoresections{% - \let\chapter=\relax - \let\unnumbered=\relax - \let\top=\relax - \let\unnumberedsec=\relax - \let\unnumberedsection=\relax - \let\unnumberedsubsec=\relax - \let\unnumberedsubsection=\relax - \let\unnumberedsubsubsec=\relax - \let\unnumberedsubsubsection=\relax - \let\section=\relax - \let\subsec=\relax - \let\subsubsec=\relax - \let\subsection=\relax - \let\subsubsection=\relax - \let\appendix=\relax - \let\appendixsec=\relax - \let\appendixsection=\relax - \let\appendixsubsec=\relax - \let\appendixsubsection=\relax - \let\appendixsubsubsec=\relax - \let\appendixsubsubsection=\relax - \let\contents=\relax - \let\smallbook=\relax - \let\titlepage=\relax -} - -% Used in nested conditionals, where we have to parse the Texinfo source -% and so want to turn off most commands, in case they are used -% incorrectly. -% -% We use \empty instead of \relax for the @def... commands, so that \end -% doesn't throw an error. For instance: -% @ignore -% @deffn ... -% @end deffn -% @end ignore -% -% The @end deffn is going to get expanded, because we're trying to allow -% nested conditionals. But we don't want to expand the actual @deffn, -% since it might be syntactically correct and intended to be ignored. -% Since \end checks for \relax, using \empty does not cause an error. -% -\def\ignoremorecommands{% - \let\defcodeindex = \relax - \let\defcv = \empty - \let\defcvx = \empty - \let\Edefcv = \empty - \let\deffn = \empty - \let\deffnx = \empty - \let\Edeffn = \empty - \let\defindex = \relax - \let\defivar = \empty - \let\defivarx = \empty - \let\Edefivar = \empty - \let\defmac = \empty - \let\defmacx = \empty - \let\Edefmac = \empty - \let\defmethod = \empty - \let\defmethodx = \empty - \let\Edefmethod = \empty - \let\defop = \empty - \let\defopx = \empty - \let\Edefop = \empty - \let\defopt = \empty - \let\defoptx = \empty - \let\Edefopt = \empty - \let\defspec = \empty - \let\defspecx = \empty - \let\Edefspec = \empty - \let\deftp = \empty - \let\deftpx = \empty - \let\Edeftp = \empty - \let\deftypefn = \empty - \let\deftypefnx = \empty - \let\Edeftypefn = \empty - \let\deftypefun = \empty - \let\deftypefunx = \empty - \let\Edeftypefun = \empty - \let\deftypeivar = \empty - \let\deftypeivarx = \empty - \let\Edeftypeivar = \empty - \let\deftypemethod = \empty - \let\deftypemethodx = \empty - \let\Edeftypemethod = \empty - \let\deftypeop = \empty - \let\deftypeopx = \empty - \let\Edeftypeop = \empty - \let\deftypevar = \empty - \let\deftypevarx = \empty - \let\Edeftypevar = \empty - \let\deftypevr = \empty - \let\deftypevrx = \empty - \let\Edeftypevr = \empty - \let\defun = \empty - \let\defunx = \empty - \let\Edefun = \empty - \let\defvar = \empty - \let\defvarx = \empty - \let\Edefvar = \empty - \let\defvr = \empty - \let\defvrx = \empty - \let\Edefvr = \empty - \let\clear = \relax - \let\down = \relax - \let\evenfooting = \relax - \let\evenheading = \relax - \let\everyfooting = \relax - \let\everyheading = \relax - \let\headings = \relax - \let\include = \relax - \let\item = \relax - \let\lowersections = \relax - \let\oddfooting = \relax - \let\oddheading = \relax - \let\printindex = \relax - \let\pxref = \relax - \let\raisesections = \relax - \let\ref = \relax - \let\set = \relax - \let\setchapternewpage = \relax - \let\setchapterstyle = \relax - \let\settitle = \relax - \let\up = \relax - \let\verbatiminclude = \relax - \let\xref = \relax + +% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext, +% @ifnotxml always succeed. They currently do nothing; we don't +% attempt to check whether the conditionals are properly nested. But we +% have to remember that they are conditionals, so that @end doesn't +% attempt to close an environment group. +% +\def\makecond#1{% + \expandafter\let\csname #1\endcsname = \relax + \expandafter\let\csname iscond.#1\endcsname = 1 } +\makecond{iftex} +\makecond{ifnotdocbook} +\makecond{ifnothtml} +\makecond{ifnotinfo} +\makecond{ifnotplaintext} +\makecond{ifnotxml} % Ignore @ignore, @ifhtml, @ifinfo, and the like. % \def\direntry{\doignore{direntry}} -\def\documentdescriptionword{documentdescription} \def\documentdescription{\doignore{documentdescription}} +\def\docbook{\doignore{docbook}} \def\html{\doignore{html}} +\def\ifdocbook{\doignore{ifdocbook}} \def\ifhtml{\doignore{ifhtml}} \def\ifinfo{\doignore{ifinfo}} \def\ifnottex{\doignore{ifnottex}} @@ -2666,198 +2721,133 @@ width0pt\relax} \fi \def\menu{\doignore{menu}} \def\xml{\doignore{xml}} -% @dircategory CATEGORY -- specify a category of the dir file -% which this file should belong to. Ignore this in TeX. -\let\dircategory = \comment - -% Ignore text until a line `@end #1'. +% Ignore text until a line `@end #1', keeping track of nested conditionals. % +% A count to remember the depth of nesting. +\newcount\doignorecount + \def\doignore#1{\begingroup - % Don't complain about control sequences we have declared \outer. - \ignoresections - % - % Define a command to swallow text until we reach `@end #1'. - % This @ is a catcode 12 token (that is the normal catcode of @ in - % this texinfo.tex file). We change the catcode of @ below to match. - \long\def\doignoretext##1@end #1{\enddoignore}% + % Scan in ``verbatim'' mode: + \catcode`\@ = \other + \catcode`\{ = \other + \catcode`\} = \other % % Make sure that spaces turn into tokens that match what \doignoretext wants. - \catcode\spaceChar = 10 - % - % Ignore braces, too, so mismatched braces don't cause trouble. - \catcode`\{ = 9 - \catcode`\} = 9 + \spaceisspace % - % We must not have @c interpreted as a control sequence. - \catcode`\@ = 12 - % - \def\ignoreword{#1}% - \ifx\ignoreword\documentdescriptionword - % The c kludge breaks documentdescription, since - % `documentdescription' contains a `c'. Means not everything will - % be ignored inside @documentdescription, but oh well... - \else - % Make the letter c a comment character so that the rest of the line - % will be ignored. This way, the document can have (for example) - % @c @end ifinfo - % and the @end ifinfo will be properly ignored. - % (We've just changed @ to catcode 12.) - \catcode`\c = 14 - \fi + % Count number of #1's that we've seen. + \doignorecount = 0 % - % And now expand the command defined above. - \doignoretext -} - -% What we do to finish off ignored text. -% -\def\enddoignore{\endgroup\ignorespaces}% - -\newif\ifwarnedobs\warnedobsfalse -\def\obstexwarn{% - \ifwarnedobs\relax\else - % We need to warn folks that they may have trouble with TeX 3.0. - % This uses \immediate\write16 rather than \message to get newlines. - \immediate\write16{} - \immediate\write16{WARNING: for users of Unix TeX 3.0!} - \immediate\write16{This manual trips a bug in TeX version 3.0 (tex hangs).} - \immediate\write16{If you are running another version of TeX, relax.} - \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.} - \immediate\write16{ Then upgrade your TeX installation if you can.} - \immediate\write16{ (See ftp://ftp.gnu.org/non-gnu/TeX.README.)} - \immediate\write16{If you are stuck with version 3.0, run the} - \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} - \immediate\write16{ to use a workaround.} - \immediate\write16{} - \global\warnedobstrue - \fi + % Swallow text until we reach the matching `@end #1'. + \dodoignore {#1}% } -% **In TeX 3.0, setting text in \nullfont hangs tex. For a -% workaround (which requires the file ``dummy.tfm'' to be installed), -% uncomment the following line: -%%%%%\font\nullfont=dummy\let\obstexwarn=\relax - -% Ignore text, except that we keep track of conditional commands for -% purposes of nesting, up to an `@end #1' command. -% -\def\nestedignore#1{% - \obstexwarn - % We must actually expand the ignored text to look for the @end - % command, so that nested ignore constructs work. Thus, we put the - % text into a \vbox and then do nothing with the result. To minimize - % the chance of memory overflow, we follow the approach outlined on - % page 401 of the TeXbook. +{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source. + \obeylines % % - \setbox0 = \vbox\bgroup - % Don't complain about control sequences we have declared \outer. - \ignoresections - % - % Define `@end #1' to end the box, which will in turn undefine the - % @end command again. - \expandafter\def\csname E#1\endcsname{\egroup\ignorespaces}% - % - % We are going to be parsing Texinfo commands. Most cause no - % trouble when they are used incorrectly, but some commands do - % complicated argument parsing or otherwise get confused, so we - % undefine them. - % - % We can't do anything about stray @-signs, unfortunately; - % they'll produce `undefined control sequence' errors. - \ignoremorecommands - % - % Set the current font to be \nullfont, a TeX primitive, and define - % all the font commands to also use \nullfont. We don't use - % dummy.tfm, as suggested in the TeXbook, because some sites - % might not have that installed. Therefore, math mode will still - % produce output, but that should be an extremely small amount of - % stuff compared to the main input. + \gdef\dodoignore#1{% + % #1 contains the string `ifinfo'. % - \nullfont - \let\tenrm=\nullfont \let\tenit=\nullfont \let\tensl=\nullfont - \let\tenbf=\nullfont \let\tentt=\nullfont \let\smallcaps=\nullfont - \let\tensf=\nullfont - % Similarly for index fonts. - \let\smallrm=\nullfont \let\smallit=\nullfont \let\smallsl=\nullfont - \let\smallbf=\nullfont \let\smalltt=\nullfont \let\smallsc=\nullfont - \let\smallsf=\nullfont - % Similarly for smallexample fonts. - \let\smallerrm=\nullfont \let\smallerit=\nullfont \let\smallersl=\nullfont - \let\smallerbf=\nullfont \let\smallertt=\nullfont \let\smallersc=\nullfont - \let\smallersf=\nullfont + % Define a command to find the next `@end #1', which must be on a line + % by itself. + \long\def\doignoretext##1^^M@end #1{\doignoretextyyy##1^^M@#1\_STOP_}% + % And this command to find another #1 command, at the beginning of a + % line. (Otherwise, we would consider a line `@c @ifset', for + % example, to count as an @ifset for nesting.) + \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}% % - % Don't complain when characters are missing from the fonts. - \tracinglostchars = 0 - % - % Don't bother to do space factor calculations. - \frenchspacing - % - % Don't report underfull hboxes. - \hbadness = 10000 - % - % Do minimal line-breaking. - \pretolerance = 10000 - % - % Do not execute instructions in @tex. - \def\tex{\doignore{tex}}% - % Do not execute macro definitions. - % `c' is a comment character, so the word `macro' will get cut off. - \def\macro{\doignore{ma}}% + % And now expand that command. + \obeylines % + \doignoretext ^^M% + }% } +\def\doignoreyyy#1{% + \def\temp{#1}% + \ifx\temp\empty % Nothing found. + \let\next\doignoretextzzz + \else % Found a nested condition, ... + \advance\doignorecount by 1 + \let\next\doignoretextyyy % ..., look for another. + % If we're here, #1 ends with ^^M\ifinfo (for example). + \fi + \next #1% the token \_STOP_ is present just after this macro. +} + +% We have to swallow the remaining "\_STOP_". +% +\def\doignoretextzzz#1{% + \ifnum\doignorecount = 0 % We have just found the outermost @end. + \let\next\enddoignore + \else % Still inside a nested condition. + \advance\doignorecount by -1 + \let\next\doignoretext % Look for the next @end. + \fi + \next +} + +% Finish off ignored text. +\def\enddoignore{\endgroup\ignorespaces} + + % @set VAR sets the variable VAR to an empty value. % @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. % % Since we want to separate VAR from REST-OF-LINE (which might be % empty), we can't just use \parsearg; we have to insert a space of our % own to delimit the rest of the line, and then take it out again if we -% didn't need it. Make sure the catcode of space is correct to avoid -% losing inside @example, for instance. +% didn't need it. +% We rely on the fact that \parsearg sets \catcode`\ =10. % -\def\set{\begingroup\catcode` =10 - \catcode`\-=12 \catcode`\_=12 % Allow - and _ in VAR. - \parsearg\setxxx} -\def\setxxx#1{\setyyy#1 \endsetyyy} +\parseargdef\set{\setyyy#1 \endsetyyy} \def\setyyy#1 #2\endsetyyy{% - \def\temp{#2}% - \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty - \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted. - \fi - \endgroup + {% + \makevalueexpandable + \def\temp{#2}% + \edef\next{\gdef\makecsname{SET#1}}% + \ifx\temp\empty + \next{}% + \else + \setzzz#2\endsetzzz + \fi + }% } -% Can't use \xdef to pre-expand #2 and save some time, since \temp or -% \next or other control sequences that we've defined might get us into -% an infinite loop. Consider `@set foo @cite{bar}'. -\def\setzzz#1#2 \endsetzzz{\expandafter\gdef\csname SET#1\endcsname{#2}} +% Remove the trailing space \setxxx inserted. +\def\setzzz#1 \endsetzzz{\next{#1}} % @clear VAR clears (i.e., unsets) the variable VAR. % -\def\clear{\parsearg\clearxxx} -\def\clearxxx#1{\global\expandafter\let\csname SET#1\endcsname=\relax} +\parseargdef\clear{% + {% + \makevalueexpandable + \global\expandafter\let\csname SET#1\endcsname=\relax + }% +} % @value{foo} gets the text saved in variable foo. +\def\value{\begingroup\makevalueexpandable\valuexxx} +\def\valuexxx#1{\expandablevalue{#1}\endgroup} { - \catcode`\_ = \active + \catcode`\- = \active \catcode`\_ = \active % - % We might end up with active _ or - characters in the argument if - % we're called from @code, as @code{@value{foo-bar_}}. So \let any - % such active characters to their normal equivalents. - \gdef\value{\begingroup + \gdef\makevalueexpandable{% + \let\value = \expandablevalue + % We don't want these characters active, ... \catcode`\-=\other \catcode`\_=\other - \indexbreaks \let_\normalunderscore - \valuexxx} + % ..., but we might end up with active ones in the argument if + % we're called from @code, as @code{@value{foo-bar_}}, though. + % So \let them to their normal equivalents. + \let-\realdash \let_\normalunderscore + } } -\def\valuexxx#1{\expandablevalue{#1}\endgroup} % We have this subroutine so that we can handle at least some @value's -% properly in indexes (we \let\value to this in \indexdummies). Ones -% whose names contain - or _ still won't work, but we can't do anything -% about that. The command has to be fully expandable (if the variable -% is set), since the result winds up in the index file. This means that -% if the variable's value contains other Texinfo commands, it's almost -% certain it will fail (although perhaps we could fix that with -% sufficient work to do a one-level expansion on the result, instead of -% complete). +% properly in indexes (we call \makevalueexpandable in \indexdummies). +% The command has to be fully expandable (if the variable is set), since +% the result winds up in the index file. This means that if the +% variable's value contains other Texinfo commands, it's almost certain +% it will fail (although perhaps we could fix that with sufficient work +% to do a one-level expansion on the result, instead of complete). % \def\expandablevalue#1{% \expandafter\ifx\csname SET#1\endcsname\relax @@ -2871,55 +2861,36 @@ width0pt\relax} \fi % @ifset VAR ... @end ifset reads the `...' iff VAR has been defined % with @set. % -\def\ifset{\parsearg\doifset} -\def\doifset#1{% - \expandafter\ifx\csname SET#1\endcsname\relax - \let\next=\ifsetfail - \else - \let\next=\ifsetsucceed - \fi - \next +% To get special treatment of `@end ifset,' call \makeond and the redefine. +% +\makecond{ifset} +\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}} +\def\doifset#1#2{% + {% + \makevalueexpandable + \let\next=\empty + \expandafter\ifx\csname SET#2\endcsname\relax + #1% If not set, redefine \next. + \fi + \expandafter + }\next } -\def\ifsetsucceed{\conditionalsucceed{ifset}} -\def\ifsetfail{\nestedignore{ifset}} -\defineunmatchedend{ifset} +\def\ifsetfail{\doignore{ifset}} % @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been % defined with @set, or has been undefined with @clear. % -\def\ifclear{\parsearg\doifclear} -\def\doifclear#1{% - \expandafter\ifx\csname SET#1\endcsname\relax - \let\next=\ifclearsucceed - \else - \let\next=\ifclearfail - \fi - \next -} -\def\ifclearsucceed{\conditionalsucceed{ifclear}} -\def\ifclearfail{\nestedignore{ifclear}} -\defineunmatchedend{ifclear} - -% @iftex, @ifnothtml, @ifnotinfo, @ifnotplaintext always succeed; we -% read the text following, through the first @end iftex (etc.). Make -% `@end iftex' (etc.) valid only after an @iftex. +% The `\else' inside the `\doifset' parameter is a trick to reuse the +% above code: if the variable is not set, do nothing, if it is set, +% then redefine \next to \ifclearfail. % -\def\iftex{\conditionalsucceed{iftex}} -\def\ifnothtml{\conditionalsucceed{ifnothtml}} -\def\ifnotinfo{\conditionalsucceed{ifnotinfo}} -\def\ifnotplaintext{\conditionalsucceed{ifnotplaintext}} -\defineunmatchedend{iftex} -\defineunmatchedend{ifnothtml} -\defineunmatchedend{ifnotinfo} -\defineunmatchedend{ifnotplaintext} +\makecond{ifclear} +\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}} +\def\ifclearfail{\doignore{ifclear}} -% True conditional. Since \set globally defines its variables, we can -% just start and end a group (to keep the @end definition undefined at -% the outer level). -% -\def\conditionalsucceed#1{\begingroup - \expandafter\def\csname E#1\endcsname{\endgroup}% -} +% @dircategory CATEGORY -- specify a category of the dir file +% which this file should belong to. Ignore this in TeX. +\let\dircategory=\comment % @defininfoenclose. \let\definfoenclose=\comment @@ -3109,6 +3080,10 @@ width0pt\relax} \fi \definedummyword{oe}% \definedummyword{o}% \definedummyword{ss}% + \definedummyword{exclamdown}% + \definedummyword{questiondown}% + \definedummyword{ordm}% + \definedummyword{ordf}% % % Although these internal commands shouldn't show up, sometimes they do. \definedummyword{bf}% @@ -3127,6 +3102,7 @@ width0pt\relax} \fi \definedummyword{sc}% \definedummyword{t}% % + \definedummyword{LaTeX}% \definedummyword{TeX}% \definedummyword{acronym}% \definedummyword{cite}% @@ -3146,11 +3122,13 @@ width0pt\relax} \fi \definedummyword{uref}% \definedummyword{url}% \definedummyword{var}% + \definedummyword{verb}% \definedummyword{w}% % % Assorted special characters. \definedummyword{bullet}% \definedummyword{copyright}% + \definedummyword{registeredsymbol}% \definedummyword{dots}% \definedummyword{enddots}% \definedummyword{equiv}% @@ -3162,10 +3140,9 @@ width0pt\relax} \fi \definedummyword{print}% \definedummyword{result}% % - % Handle some cases of @value -- where the variable name does not - % contain - or _, and the value does not contain any + % Handle some cases of @value -- where it does not contain any % (non-fully-expandable) commands. - \let\value = \expandablevalue + \makevalueexpandable % % Normal spaces, not active ones. \unsepspaces @@ -3174,18 +3151,13 @@ width0pt\relax} \fi \turnoffmacros } -% If an index command is used in an @example environment, any spaces -% therein should become regular spaces in the raw index file, not the -% expansion of \tie (\leavevmode \penalty \@M \ ). -{\obeyspaces - \gdef\unsepspaces{\obeyspaces\let =\space}} - % \indexnofonts is used when outputting the strings to sort the index % by, and when constructing control sequence names. It eliminates all % control sequences and just writes whatever the best ASCII sort string % would be for a given command (usually its argument). % +\def\indexdummylatex{LaTeX} \def\indexdummytex{TeX} \def\indexdummydots{...} % @@ -3226,6 +3198,8 @@ width0pt\relax} \fi \def\ss{ss}% \def\exclamdown{!}% \def\questiondown{?}% + \def\ordf{a}% + \def\ordm{o}% % % Don't no-op \tt, since it isn't a user-level command % and is used in the definitions of the active chars like <, >, |, etc. @@ -3239,6 +3213,7 @@ width0pt\relax} \fi \let\sc=\asis \let\t=\asis % + \let\LaTeX=\indexdummylatex \let\TeX=\indexdummytex \let\acronym=\asis \let\cite=\asis @@ -3258,98 +3233,145 @@ width0pt\relax} \fi \let\uref=\asis \let\url=\asis \let\var=\asis + \let\verb=\asis \let\w=\asis } \let\indexbackslash=0 %overridden during \printindex. \let\SETmarginindex=\relax % put index entries in margin (undocumented)? -% For \ifx comparisons. -\def\emptymacro{\empty} - % Most index entries go through here, but \dosubind is the general case. -% -\def\doind#1#2{\dosubind{#1}{#2}\empty} +% #1 is the index name, #2 is the entry text. +\def\doind#1#2{\dosubind{#1}{#2}{}} % Workhorse for all \fooindexes. % #1 is name of index, #2 is stuff to put there, #3 is subentry -- -% \empty if called from \doind, as we usually are. The main exception -% is with defuns, which call us directly. +% empty if called from \doind, as we usually are (the main exception +% is with most defuns, which call us directly). % \def\dosubind#1#2#3{% + \iflinks + {% + % Store the main index entry text (including the third arg). + \toks0 = {#2}% + % If third arg is present, precede it with a space. + \def\thirdarg{#3}% + \ifx\thirdarg\empty \else + \toks0 = \expandafter{\the\toks0 \space #3}% + \fi + % + \edef\writeto{\csname#1indfile\endcsname}% + % + \ifvmode + \dosubindsanitize + \else + \dosubindwrite + \fi + }% + \fi +} + +% Write the entry in \toks0 to the index file: +% +\def\dosubindwrite{% % Put the index entry in the margin if desired. \ifx\SETmarginindex\relax\else - \insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}% + \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}% \fi - {% - \count255=\lastpenalty - {% - \indexdummies % Must do this here, since \bf, etc expand at this stage - \escapechar=`\\ - {% - \let\folio = 0% We will expand all macros now EXCEPT \folio. - \def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now - % so it will be output as is; and it will print as backslash. - % - % The main index entry text. - \toks0 = {#2}% - % - % If third arg is present, precede it with space in sort key. - \def\thirdarg{#3}% - \ifx\thirdarg\emptymacro \else - % If the third (subentry) arg is present, add it to the index - % line to write. - \toks0 = \expandafter{\the\toks0 \space #3}% - \fi - % - % Process the index entry with all font commands turned off, to - % get the string to sort by. - {\indexnofonts - \edef\temp{\the\toks0}% need full expansion - \xdef\indexsorttmp{\temp}% - }% - % - % Set up the complete index entry, with both the sort key and - % the original text, including any font commands. We write - % three arguments to \entry to the .?? file (four in the - % subentry case), texindex reduces to two when writing the .??s - % sorted result. - \edef\temp{% - \write\csname#1indfile\endcsname{% - \realbackslash entry{\indexsorttmp}{\folio}{\the\toks0}}% - }% - % - % If a skip is the last thing on the list now, preserve it - % by backing up by \lastskip, doing the \write, then inserting - % the skip again. Otherwise, the whatsit generated by the - % \write will make \lastskip zero. The result is that sequences - % like this: - % @end defun - % @tindex whatever - % @defun ... - % will have extra space inserted, because the \medbreak in the - % start of the @defun won't see the skip inserted by the @end of - % the previous defun. - % - % But don't do any of this if we're not in vertical mode. We - % don't want to do a \vskip and prematurely end a paragraph. - % - % Avoid page breaks due to these extra skips, too. - % - \iflinks - \ifvmode - \skip0 = \lastskip - \ifdim\lastskip = 0pt \else \nobreak\vskip-\skip0 \fi - \fi - % - \temp % do the write - % - \ifvmode \ifdim\skip0 = 0pt \else \nobreak\vskip\skip0 \fi \fi - \fi - }% - }% - \penalty\count255 + % + % Remember, we are within a group. + \indexdummies % Must do this here, since \bf, etc expand at this stage + \escapechar=`\\ + \def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now + % so it will be output as is; and it will print as backslash. + % + % Process the index entry with all font commands turned off, to + % get the string to sort by. + {\indexnofonts + \edef\temp{\the\toks0}% need full expansion + \xdef\indexsorttmp{\temp}% + }% + % + % Set up the complete index entry, with both the sort key and + % the original text, including any font commands. We write + % three arguments to \entry to the .?? file (four in the + % subentry case), texindex reduces to two when writing the .??s + % sorted result. + \edef\temp{% + \write\writeto{% + \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}% }% + \temp +} + +% Take care of unwanted page breaks: +% +% If a skip is the last thing on the list now, preserve it +% by backing up by \lastskip, doing the \write, then inserting +% the skip again. Otherwise, the whatsit generated by the +% \write will make \lastskip zero. The result is that sequences +% like this: +% @end defun +% @tindex whatever +% @defun ... +% will have extra space inserted, because the \medbreak in the +% start of the @defun won't see the skip inserted by the @end of +% the previous defun. +% +% But don't do any of this if we're not in vertical mode. We +% don't want to do a \vskip and prematurely end a paragraph. +% +% Avoid page breaks due to these extra skips, too. +% +% But wait, there is a catch there: +% We'll have to check whether \lastskip is zero skip. \ifdim is not +% sufficient for this purpose, as it ignores stretch and shrink parts +% of the skip. The only way seems to be to check the textual +% representation of the skip. +% +% The following is almost like \def\zeroskipmacro{0.0pt} except that +% the ``p'' and ``t'' characters have catcode \other, not 11 (letter). +% +\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname} +% +% ..., ready, GO: +% +\def\dosubindsanitize{% + % \lastskip and \lastpenalty cannot both be nonzero simultaneously. + \skip0 = \lastskip + \edef\lastskipmacro{\the\lastskip}% + \count255 = \lastpenalty + % + % If \lastskip is nonzero, that means the last item was a + % skip. And since a skip is discardable, that means this + % -\skip0 glue we're inserting is preceded by a + % non-discardable item, therefore it is not a potential + % breakpoint, therefore no \nobreak needed. + \ifx\lastskipmacro\zeroskipmacro + \else + \vskip-\skip0 + \fi + % + \dosubindwrite + % + \ifx\lastskipmacro\zeroskipmacro + % if \lastskip was zero, perhaps the last item was a + % penalty, and perhaps it was >=10000, e.g., a \nobreak. + % In that case, we want to re-insert the penalty; since we + % just inserted a non-discardable item, any following glue + % (such as a \parskip) would be a breakpoint. For example: + % @deffn deffn-whatever + % @vindex index-whatever + % Description. + % would allow a break between the index-whatever whatsit + % and the "Description." paragraph. + \ifnum\count255>9999 \nobreak \fi + \else + % On the other hand, if we had a nonzero \lastskip, + % this make-up glue would be preceded by a non-discardable item + % (the whatsit from the \write), so we must insert a \nobreak. + \nobreak\vskip\skip0 + \fi } % The index entry written in the file actually looks like @@ -3387,14 +3409,12 @@ width0pt\relax} \fi % @printindex causes a particular index (the ??s file) to get printed. % It does not print any chapter heading (usually an @unnumbered). % -\def\printindex{\parsearg\doprintindex} -\def\doprintindex#1{\begingroup +\parseargdef\printindex{\begingroup \dobreak \chapheadingskip{10000}% % \smallfonts \rm \tolerance = 9500 \everypar = {}% don't want the \kern\-parindent from indentation suppression. - \indexbreaks % % See if the index file exists and is nonempty. % Change catcode of @ here so that if the index file contains @@ -3459,74 +3479,94 @@ width0pt\relax} \fi \nobreak }} -% This typesets a paragraph consisting of #1, dot leaders, and then #2 -% flush to the right margin. It is used for index and table of contents -% entries. The paragraph is indented by \leftskip. -% -\def\entry#1#2{\begingroup - % - % Start a new paragraph if necessary, so our assignments below can't - % affect previous text. - \par - % - % Do not fill out the last line with white space. - \parfillskip = 0in - % - % No extra space above this paragraph. - \parskip = 0in - % - % Do not prefer a separate line ending with a hyphen to fewer lines. - \finalhyphendemerits = 0 - % - % \hangindent is only relevant when the entry text and page number - % don't both fit on one line. In that case, bob suggests starting the - % dots pretty far over on the line. Unfortunately, a large - % indentation looks wrong when the entry text itself is broken across - % lines. So we use a small indentation and put up with long leaders. - % - % \hangafter is reset to 1 (which is the value we want) at the start - % of each paragraph, so we need not do anything with that. - \hangindent = 2em - % - % When the entry text needs to be broken, just fill out the first line - % with blank space. - \rightskip = 0pt plus1fil - % - % A bit of stretch before each entry for the benefit of balancing columns. - \vskip 0pt plus1pt - % - % Start a ``paragraph'' for the index entry so the line breaking - % parameters we've set above will have an effect. - \noindent - % - % Insert the text of the index entry. TeX will do line-breaking on it. - #1% - % The following is kludged to not output a line of dots in the index if - % there are no page numbers. The next person who breaks this will be - % cursed by a Unix daemon. - \def\tempa{{\rm }}% - \def\tempb{#2}% - \edef\tempc{\tempa}% - \edef\tempd{\tempb}% - \ifx\tempc\tempd\ \else% +% \entry typesets a paragraph consisting of the text (#1), dot leaders, and +% then page number (#2) flushed to the right margin. It is used for index +% and table of contents entries. The paragraph is indented by \leftskip. +% +% A straigtforward implementation would start like this: +% \def\entry#1#2{... +% But this frozes the catcodes in the argument, and can cause problems to +% @code, which set's active ``-''. This problem was fixed by a kludge--- +% ``-'' was active throughout whole index, but this isn't what we really +% want. +% The right solution is to prevent \entry from swallowing the whole text. +% --kasal, 21nov03 +\def\entry{% + \begingroup + % + % Start a new paragraph if necessary, so our assignments below can't + % affect previous text. + \par + % + % Do not fill out the last line with white space. + \parfillskip = 0in + % + % No extra space above this paragraph. + \parskip = 0in + % + % Do not prefer a separate line ending with a hyphen to fewer lines. + \finalhyphendemerits = 0 % - % If we must, put the page number on a line of its own, and fill out - % this line with blank space. (The \hfil is overwhelmed with the - % fill leaders glue in \indexdotfill if the page number does fit.) - \hfil\penalty50 - \null\nobreak\indexdotfill % Have leaders before the page number. + % \hangindent is only relevant when the entry text and page number + % don't both fit on one line. In that case, bob suggests starting the + % dots pretty far over on the line. Unfortunately, a large + % indentation looks wrong when the entry text itself is broken across + % lines. So we use a small indentation and put up with long leaders. % - % The `\ ' here is removed by the implicit \unskip that TeX does as - % part of (the primitive) \par. Without it, a spurious underfull - % \hbox ensues. - \ifpdf - \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. + % \hangafter is reset to 1 (which is the value we want) at the start + % of each paragraph, so we need not do anything with that. + \hangindent = 2em + % + % When the entry text needs to be broken, just fill out the first line + % with blank space. + \rightskip = 0pt plus1fil + % + % A bit of stretch before each entry for the benefit of balancing + % columns. + \vskip 0pt plus1pt + % + % Swallow the left brace of the text (first parameter): + \afterassignment\doentry + \let\temp = +} +\def\doentry{% + \bgroup % Instead of the swallowed brace. + \noindent + \aftergroup\finishentry + % And now comes the text of the entry. +} +\def\finishentry#1{% + % #1 is the page number. + % + % The following is kludged to not output a line of dots in the index if + % there are no page numbers. The next person who breaks this will be + % cursed by a Unix daemon. + \def\tempa{{\rm }}% + \def\tempb{#1}% + \edef\tempc{\tempa}% + \edef\tempd{\tempb}% + \ifx\tempc\tempd + \ % \else - \ #2% The page number ends the paragraph. + % + % If we must, put the page number on a line of its own, and fill out + % this line with blank space. (The \hfil is overwhelmed with the + % fill leaders glue in \indexdotfill if the page number does fit.) + \hfil\penalty50 + \null\nobreak\indexdotfill % Have leaders before the page number. + % + % The `\ ' here is removed by the implicit \unskip that TeX does as + % part of (the primitive) \par. Without it, a spurious underfull + % \hbox ensues. + \ifpdf + \pdfgettoks#1.\ \the\toksA + \else + \ #1% + \fi \fi - \fi% - \par -\endgroup} + \par + \endgroup +} % Like \dotfill except takes at least 1 em. \def\indexdotfill{\cleaders @@ -3695,6 +3735,12 @@ width0pt\relax} \fi \message{sectioning,} % Chapters, sections, etc. +% \unnumberedno is an oxymoron, of course. But we count the unnumbered +% sections so that we can refer to them unambiguously in the pdf +% outlines by their "section number". We avoid collisions with chapter +% numbers by starting them at 10000. (If a document ever has 10000 +% chapters, we're in trouble anyway, I'm sure.) +\newcount\unnumberedno \unnumberedno = 10000 \newcount\chapno \newcount\secno \secno=0 \newcount\subsecno \subsecno=0 @@ -3702,9 +3748,12 @@ width0pt\relax} \fi % This counter is funny since it counts through charcodes of letters A, B, ... \newcount\appendixno \appendixno = `\@ +% % \def\appendixletter{\char\the\appendixno} -% We do the following for the sake of pdftex, which needs the actual +% We do the following ugly conditional instead of the above simple +% construct for the sake of pdftex, which needs the actual % letter in the expansion, not just typeset. +% \def\appendixletter{% \ifnum\appendixno=`A A% \else\ifnum\appendixno=`B B% @@ -3742,11 +3791,12 @@ width0pt\relax} \fi % Each @chapter defines this as the name of the chapter. % page headings and footings can use it. @section does likewise. +% However, they are not reliable, because we don't use marks. \def\thischapter{} \def\thissection{} \newcount\absseclevel % used to calculate proper heading level -\newcount\secbase\secbase=0 % @raise/lowersections modify this count +\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count % @raisesections: treat @section as chapter, @subsection as section, etc. \def\raisesections{\global\advance\secbase by -1} @@ -3761,116 +3811,105 @@ width0pt\relax} \fi % #2 is text for heading \def\numhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 \ifcase\absseclevel - \chapterzzz{#2} -\or - \seczzz{#2} -\or - \numberedsubseczzz{#2} -\or - \numberedsubsubseczzz{#2} -\else - \ifnum \absseclevel<0 - \chapterzzz{#2} + \chapterzzz{#2}% + \or \seczzz{#2}% + \or \numberedsubseczzz{#2}% + \or \numberedsubsubseczzz{#2}% \else - \numberedsubsubseczzz{#2} + \ifnum \absseclevel<0 \chapterzzz{#2}% + \else \numberedsubsubseczzz{#2}% + \fi \fi -\fi -\suppressfirstparagraphindent + \suppressfirstparagraphindent } % like \numhead, but chooses appendix heading levels \def\apphead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 \ifcase\absseclevel - \appendixzzz{#2} -\or - \appendixsectionzzz{#2} -\or - \appendixsubseczzz{#2} -\or - \appendixsubsubseczzz{#2} -\else - \ifnum \absseclevel<0 - \appendixzzz{#2} + \appendixzzz{#2}% + \or \appendixsectionzzz{#2}% + \or \appendixsubseczzz{#2}% + \or \appendixsubsubseczzz{#2}% \else - \appendixsubsubseczzz{#2} + \ifnum \absseclevel<0 \appendixzzz{#2}% + \else \appendixsubsubseczzz{#2}% + \fi \fi -\fi -\suppressfirstparagraphindent + \suppressfirstparagraphindent } % like \numhead, but chooses numberless heading levels \def\unnmhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 -\ifcase\absseclevel - \unnumberedzzz{#2} -\or - \unnumberedseczzz{#2} -\or - \unnumberedsubseczzz{#2} -\or - \unnumberedsubsubseczzz{#2} -\else - \ifnum \absseclevel<0 - \unnumberedzzz{#2} + \ifcase\absseclevel + \unnumberedzzz{#2}% + \or \unnumberedseczzz{#2}% + \or \unnumberedsubseczzz{#2}% + \or \unnumberedsubsubseczzz{#2}% \else - \unnumberedsubsubseczzz{#2} + \ifnum \absseclevel<0 \unnumberedzzz{#2}% + \else \unnumberedsubsubseczzz{#2}% + \fi \fi -\fi -\suppressfirstparagraphindent -} - -% @chapter, @appendix, @unnumbered. -\def\thischaptername{No Chapter Title} -\outer\def\chapter{\parsearg\chapteryyy} -\def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz -\def\chapterzzz #1{% - \secno=0 \subsecno=0 \subsubsecno=0 - \global\advance \chapno by 1 \message{\putwordChapter\space \the\chapno}% - \chapmacro {#1}{\the\chapno}% - \gdef\thissection{#1}% - \gdef\thischaptername{#1}% - % We don't substitute the actual chapter name into \thischapter - % because we don't want its macros evaluated now. - \xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}% - \writetocentry{chap}{#1}{{\the\chapno}} - \donoderef + \suppressfirstparagraphindent +} + +% @chapter, @appendix, @unnumbered. Increment top-level counter, reset +% all lower-level sectioning counters to zero. +% +% Also set \chaplevelprefix, which we prepend to @float sequence numbers +% (e.g., figures), q.v. By default (before any chapter), that is empty. +\let\chaplevelprefix = \empty +% +\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz +\def\chapterzzz#1{% + % section resetting is \global in case the chapter is in a group, such + % as an @include file. + \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 + \global\advance\chapno by 1 + % + % Used for \float. + \gdef\chaplevelprefix{\the\chapno.}% + \resetallfloatnos + % + \message{\putwordChapter\space \the\chapno}% + % + % Write the actual heading. + \chapmacro{#1}{Ynumbered}{\the\chapno}% + % + % So @section and the like are numbered underneath this chapter. \global\let\section = \numberedsec \global\let\subsection = \numberedsubsec \global\let\subsubsection = \numberedsubsubsec } -% we use \chapno to avoid indenting back -\def\appendixbox#1{% - \setbox0 = \hbox{\putwordAppendix{} \the\chapno}% - \hbox to \wd0{#1\hss}} - -\outer\def\appendix{\parsearg\appendixyyy} -\def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz -\def\appendixzzz #1{% - \secno=0 \subsecno=0 \subsubsecno=0 - \global\advance \appendixno by 1 - \message{\putwordAppendix\space \appendixletter}% - \chapmacro {#1}{\appendixbox{\putwordAppendix{} \appendixletter}}% - \gdef\thissection{#1}% - \gdef\thischaptername{#1}% - \xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% - \writetocentry{appendix}{#1}{{\appendixletter}} - \appendixnoderef +\outer\parseargdef\appendix{\apphead0{#1}} % normally apphead0 calls appendixzzz +\def\appendixzzz#1{% + \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 + \global\advance\appendixno by 1 + \gdef\chaplevelprefix{\appendixletter.}% + \resetallfloatnos + % + \def\appendixnum{\putwordAppendix\space \appendixletter}% + \message{\appendixnum}% + % + \chapmacro{#1}{Yappendix}{\appendixletter}% + % \global\let\section = \appendixsec \global\let\subsection = \appendixsubsec \global\let\subsubsection = \appendixsubsubsec } % @centerchap is like @unnumbered, but the heading is centered. -\outer\def\centerchap{\parsearg\centerchapyyy} -\def\centerchapyyy #1{{\let\unnumbchapmacro=\centerchapmacro \unnumberedyyy{#1}}} +\outer\parseargdef\centerchap{{\unnumberedyyy{#1}}} -% @top is like @unnumbered. -\outer\def\top{\parsearg\unnumberedyyy} - -\outer\def\unnumbered{\parsearg\unnumberedyyy} -\def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz -\def\unnumberedzzz #1{% - \secno=0 \subsecno=0 \subsubsecno=0 +\outer\parseargdef\unnumbered{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz +\def\unnumberedzzz#1{% + \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 + \global\advance\unnumberedno by 1 + % + % Since an unnumbered has no number, no prefix for figures. + \global\let\chaplevelprefix = \empty + \resetallfloatnos % % This used to be simply \message{#1}, but TeX fully expands the % argument to \message. Therefore, if #1 contained @-commands, TeX @@ -3883,112 +3922,84 @@ width0pt\relax} \fi % \the<toks register> to achieve this: TeX expands \the<toks> only once, % simply yielding the contents of <toks register>. (We also do this for % the toc entries.) - \toks0 = {#1}\message{(\the\toks0)}% + \toks0 = {#1}% + \message{(\the\toks0)}% + % + \chapmacro{#1}{Ynothing}{\the\unnumberedno}% % - \unnumbchapmacro {#1}% - \gdef\thischapter{#1}\gdef\thissection{#1}% - \writetocentry{unnumbchap}{#1}{{\the\chapno}} - \unnumbnoderef \global\let\section = \unnumberedsec \global\let\subsection = \unnumberedsubsec \global\let\subsubsection = \unnumberedsubsubsec } +% @top is like @unnumbered. +\let\top\unnumbered + % Sections. -\outer\def\numberedsec{\parsearg\secyyy} -\def\secyyy #1{\numhead1{#1}} % normally calls seczzz -\def\seczzz #1{% - \subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % - \gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% - \writetocentry{sec}{#1}{{\the\chapno}{\the\secno}} - \donoderef - \nobreak +\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz +\def\seczzz#1{% + \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 + \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}% } -\outer\def\appendixsection{\parsearg\appendixsecyyy} -\outer\def\appendixsec{\parsearg\appendixsecyyy} -\def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz -\def\appendixsectionzzz #1{% - \subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % - \gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% - \writetocentry{sec}{#1}{{\appendixletter}{\the\secno}} - \appendixnoderef - \nobreak +\outer\parseargdef\appendixsection{\apphead1{#1}} % normally calls appendixsectionzzz +\def\appendixsectionzzz#1{% + \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 + \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}% } +\let\appendixsec\appendixsection -\outer\def\unnumberedsec{\parsearg\unnumberedsecyyy} -\def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz -\def\unnumberedseczzz #1{% - \plainsecheading {#1}\gdef\thissection{#1}% - \writetocentry{unnumbsec}{#1}{{\the\chapno}{\the\secno}} - \unnumbnoderef - \nobreak +\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} % normally calls unnumberedseczzz +\def\unnumberedseczzz#1{% + \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 + \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}% } % Subsections. -\outer\def\numberedsubsec{\parsearg\numberedsubsecyyy} -\def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz -\def\numberedsubseczzz #1{% - \gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % - \subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% - \writetocentry{subsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}} - \donoderef - \nobreak +\outer\parseargdef\numberedsubsec{\numhead2{#1}} % normally calls numberedsubseczzz +\def\numberedsubseczzz#1{% + \global\subsubsecno=0 \global\advance\subsecno by 1 + \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}% } -\outer\def\appendixsubsec{\parsearg\appendixsubsecyyy} -\def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz -\def\appendixsubseczzz #1{% - \gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % - \subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% - \writetocentry{subsec}{#1}{{\appendixletter}{\the\secno}{\the\subsecno}} - \appendixnoderef - \nobreak +\outer\parseargdef\appendixsubsec{\apphead2{#1}} % normally calls appendixsubseczzz +\def\appendixsubseczzz#1{% + \global\subsubsecno=0 \global\advance\subsecno by 1 + \sectionheading{#1}{subsec}{Yappendix}% + {\appendixletter.\the\secno.\the\subsecno}% } -\outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy} -\def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz -\def\unnumberedsubseczzz #1{% - \plainsubsecheading {#1}\gdef\thissection{#1}% - \writetocentry{unnumbsubsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}} - \unnumbnoderef - \nobreak +\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} %normally calls unnumberedsubseczzz +\def\unnumberedsubseczzz#1{% + \global\subsubsecno=0 \global\advance\subsecno by 1 + \sectionheading{#1}{subsec}{Ynothing}% + {\the\unnumberedno.\the\secno.\the\subsecno}% } % Subsubsections. -\outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy} -\def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz -\def\numberedsubsubseczzz #1{% - \gdef\thissection{#1}\global\advance \subsubsecno by 1 % - \subsubsecheading {#1} - {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% - \writetocentry{subsubsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}} - \donoderef - \nobreak +\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} % normally numberedsubsubseczzz +\def\numberedsubsubseczzz#1{% + \global\advance\subsubsecno by 1 + \sectionheading{#1}{subsubsec}{Ynumbered}% + {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}% } -\outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy} -\def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz -\def\appendixsubsubseczzz #1{% - \gdef\thissection{#1}\global\advance \subsubsecno by 1 % - \subsubsecheading {#1} - {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% - \writetocentry{subsubsec}{#1}{{\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}} - \appendixnoderef - \nobreak +\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} % normally appendixsubsubseczzz +\def\appendixsubsubseczzz#1{% + \global\advance\subsubsecno by 1 + \sectionheading{#1}{subsubsec}{Yappendix}% + {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}% } -\outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy} -\def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz -\def\unnumberedsubsubseczzz #1{% - \plainsubsubsecheading {#1}\gdef\thissection{#1}% - \writetocentry{unnumbsubsubsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}} - \unnumbnoderef - \nobreak +\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} %normally unnumberedsubsubseczzz +\def\unnumberedsubsubseczzz#1{% + \global\advance\subsubsecno by 1 + \sectionheading{#1}{subsubsec}{Ynothing}% + {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}% } % These are variants which are not "outer", so they can appear in @ifinfo. -% Actually, they should now be obsolete; ordinary section commands should work. +% Actually, they are now be obsolete; ordinary section commands should work. \def\infotop{\parsearg\unnumberedzzz} \def\infounnumbered{\parsearg\unnumberedzzz} \def\infounnumberedsec{\parsearg\unnumberedseczzz} @@ -4008,9 +4019,9 @@ width0pt\relax} \fi % These macros control what the section commands do, according % to what kind of chapter we are in (ordinary, appendix, or unnumbered). % Define them by default for a numbered chapter. -\global\let\section = \numberedsec -\global\let\subsection = \numberedsubsec -\global\let\subsubsection = \numberedsubsubsec +\let\section = \numberedsec +\let\subsection = \numberedsubsec +\let\subsubsection = \numberedsubsubsec % Define @majorheading, @heading and @subheading @@ -4023,23 +4034,27 @@ width0pt\relax} \fi % if justification is not attempted. Hence \raggedright. -\def\majorheading{\parsearg\majorheadingzzz} -\def\majorheadingzzz #1{% +\def\majorheading{% {\advance\chapheadingskip by 10pt \chapbreak }% - {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\penalty 200} + \parsearg\chapheadingzzz +} -\def\chapheading{\parsearg\chapheadingzzz} -\def\chapheadingzzz #1{\chapbreak % +\def\chapheading{\chapbreak \parsearg\chapheadingzzz} +\def\chapheadingzzz#1{% {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\penalty 200} + \rm #1\hfill}}% + \bigskip \par\penalty 200\relax + \suppressfirstparagraphindent +} % @heading, @subheading, @subsubheading. -\def\heading{\parsearg\plainsecheading} -\def\subheading{\parsearg\plainsubsecheading} -\def\subsubheading{\parsearg\plainsubsubsecheading} +\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{} + \suppressfirstparagraphindent} +\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{} + \suppressfirstparagraphindent} +\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{} + \suppressfirstparagraphindent} % These macros generate a chapter, section, etc. heading only % (including whitespace, linebreaking, etc. around it), @@ -4072,7 +4087,7 @@ width0pt\relax} \fi \global\let\pagealignmacro=\chappager \global\def\HEADINGSon{\HEADINGSsingle}} -\def\CHAPPAGodd{ +\def\CHAPPAGodd{% \global\let\contentsalignmacro = \chapoddpage \global\let\pchapsepmacro=\chapoddpage \global\let\pagealignmacro=\chapoddpage @@ -4080,30 +4095,79 @@ width0pt\relax} \fi \CHAPPAGon -\def\CHAPFplain{ +\def\CHAPFplain{% \global\let\chapmacro=\chfplain -\global\let\unnumbchapmacro=\unnchfplain \global\let\centerchapmacro=\centerchfplain} -% Plain chapter opening. -% #1 is the text, #2 the chapter number or empty if unnumbered. -\def\chfplain#1#2{% +% Normal chapter opening. +% +% #1 is the text, #2 is the section type (Ynumbered, Ynothing, +% Yappendix, Yomitfromtoc), #3 the chapter number. +% +% To test against our argument. +\def\Ynothingkeyword{Ynothing} +\def\Yomitfromtockeyword{Yomitfromtoc} +\def\Yappendixkeyword{Yappendix} +% +\def\chfplain#1#2#3{% \pchapsepmacro {% \chapfonts \rm - \def\chapnum{#2}% - \setbox0 = \hbox{#2\ifx\chapnum\empty\else\enspace\fi}% + % + % Have to define \thissection before calling \donoderef, because the + % xref code eventually uses it. On the other hand, it has to be called + % after \pchapsepmacro, or the headline will change too soon. + \gdef\thissection{#1}% + \gdef\thischaptername{#1}% + % + % Only insert the separating space if we have a chapter/appendix + % number, and don't print the unnumbered ``number''. + \def\temptype{#2}% + \ifx\temptype\Ynothingkeyword + \setbox0 = \hbox{}% + \def\toctype{unnchap}% + \def\thischapter{#1}% + \else\ifx\temptype\Yomitfromtockeyword + \setbox0 = \hbox{}% contents like unnumbered, but no toc entry + \def\toctype{omit}% + \xdef\thischapter{}% + \else\ifx\temptype\Yappendixkeyword + \setbox0 = \hbox{\putwordAppendix{} #3\enspace}% + \def\toctype{app}% + % We don't substitute the actual chapter name into \thischapter + % because we don't want its macros evaluated now. And we don't + % use \thissection because that changes with each section. + % + \xdef\thischapter{\putwordAppendix{} \appendixletter: + \noexpand\thischaptername}% + \else + \setbox0 = \hbox{#3\enspace}% + \def\toctype{numchap}% + \xdef\thischapter{\putwordChapter{} \the\chapno: + \noexpand\thischaptername}% + \fi\fi\fi + % + % Write the toc entry for this chapter. Must come before the + % \donoderef, because we include the current node name in the toc + % entry, and \donoderef resets it to empty. + \writetocentry{\toctype}{#1}{#3}% + % + % For pdftex, we have to write out the node definition (aka, make + % the pdfdest) after any page break, but before the actual text has + % been typeset. If the destination for the pdf outline is after the + % text, then jumping from the outline may wind up with the text not + % being visible, for instance under high magnification. + \donoderef{#2}% + % + % Typeset the actual heading. \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright - \hangindent = \wd0 \centerparametersmaybe + \hangindent=\wd0 \centerparametersmaybe \unhbox0 #1\par}% }% \nobreak\bigskip % no page break after a chapter title \nobreak } -% Plain opening for unnumbered. -\def\unnchfplain#1{\chfplain{#1}{}} - % @centerchap -- centered and unnumbered. \let\centerparametersmaybe = \relax \def\centerchfplain#1{{% @@ -4112,11 +4176,14 @@ width0pt\relax} \fi \leftskip = \rightskip \parfillskip = 0pt }% - \chfplain{#1}{}% + \chfplain{#1}{Ynothing}{}% }} \CHAPFplain % The default +% I don't think this chapter style is supported any more, so I'm not +% updating it with the new noderef stuff. We'll see. --karl, 11aug03. +% \def\unnchfopen #1{% \chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 \parindent=0pt\raggedright @@ -4134,61 +4201,95 @@ width0pt\relax} \fi \hfill {\rm #1}\hfill}}\bigskip \par\nobreak } -\def\CHAPFopen{ +\def\CHAPFopen{% \global\let\chapmacro=\chfopen -\global\let\unnumbchapmacro=\unnchfopen \global\let\centerchapmacro=\centerchfopen} -% Section titles. +% Section titles. These macros combine the section number parts and +% call the generic \sectionheading to do the printing. +% \newskip\secheadingskip -\def\secheadingbreak{\dobreak \secheadingskip {-1000}} -\def\secheading#1#2#3{\sectionheading{sec}{#2.#3}{#1}} -\def\plainsecheading#1{\sectionheading{sec}{}{#1}} +\def\secheadingbreak{\dobreak \secheadingskip{-1000}} % Subsection titles. -\newskip \subsecheadingskip -\def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}} -\def\subsecheading#1#2#3#4{\sectionheading{subsec}{#2.#3.#4}{#1}} -\def\plainsubsecheading#1{\sectionheading{subsec}{}{#1}} +\newskip\subsecheadingskip +\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}} % Subsubsection titles. -\let\subsubsecheadingskip = \subsecheadingskip -\let\subsubsecheadingbreak = \subsecheadingbreak -\def\subsubsecheading#1#2#3#4#5{\sectionheading{subsubsec}{#2.#3.#4.#5}{#1}} -\def\plainsubsubsecheading#1{\sectionheading{subsubsec}{}{#1}} +\def\subsubsecheadingskip{\subsecheadingskip} +\def\subsubsecheadingbreak{\subsecheadingbreak} -% Print any size section title. -% -% #1 is the section type (sec/subsec/subsubsec), #2 is the section -% number (maybe empty), #3 the text. -\def\sectionheading#1#2#3{% - {% - \expandafter\advance\csname #1headingskip\endcsname by \parskip - \csname #1headingbreak\endcsname - }% +% Print any size, any type, section title. +% +% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is +% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the +% section number. +% +\def\sectionheading#1#2#3#4{% {% % Switch to the right set of fonts. - \csname #1fonts\endcsname \rm + \csname #2fonts\endcsname \rm + % + % Insert space above the heading. + \csname #2headingbreak\endcsname % - % Only insert the separating space if we have a section number. - \def\secnum{#2}% - \setbox0 = \hbox{#2\ifx\secnum\empty\else\enspace\fi}% + % Only insert the space after the number if we have a section number. + \def\sectionlevel{#2}% + \def\temptype{#3}% + % + \ifx\temptype\Ynothingkeyword + \setbox0 = \hbox{}% + \def\toctype{unn}% + \gdef\thissection{#1}% + \else\ifx\temptype\Yomitfromtockeyword + % for @headings -- no section number, don't include in toc, + % and don't redefine \thissection. + \setbox0 = \hbox{}% + \def\toctype{omit}% + \let\sectionlevel=\empty + \else\ifx\temptype\Yappendixkeyword + \setbox0 = \hbox{#4\enspace}% + \def\toctype{app}% + \gdef\thissection{#1}% + \else + \setbox0 = \hbox{#4\enspace}% + \def\toctype{num}% + \gdef\thissection{#1}% + \fi\fi\fi % + % Write the toc entry (before \donoderef). See comments in \chfplain. + \writetocentry{\toctype\sectionlevel}{#1}{#4}% + % + % Write the node reference (= pdf destination for pdftex). + % Again, see comments in \chfplain. + \donoderef{#3}% + % + % Output the actual section heading. \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright - \hangindent = \wd0 % zero if no section number - \unhbox0 #3}% + \hangindent=\wd0 % zero if no section number + \unhbox0 #1}% }% - % Add extra space after the heading -- either a line space or a - % paragraph space, whichever is more. (Some people like to set - % \parskip to large values for some reason.) Don't allow stretch, though. + % Add extra space after the heading -- half of whatever came above it. + % Don't allow stretch, though. + \kern .5 \csname #2headingskip\endcsname + % + % Do not let the kern be a potential breakpoint, as it would be if it + % was followed by glue. \nobreak - \ifdim\parskip>\normalbaselineskip - \kern\parskip - \else - \kern\normalbaselineskip - \fi + % + % We'll almost certainly start a paragraph next, so don't let that + % glue accumulate. (Not a breakpoint because it's preceded by a + % discardable item.) + \vskip-\parskip + % + % This \nobreak is purely so the last item on the list is a \penalty + % of 10000. This is so other code, for instance \parsebodycommon, can + % check for and avoid allowing breakpoints. Otherwise, it would + % insert a valid breakpoint between: + % @section sec-whatever + % @deffn def-whatever \nobreak } @@ -4198,119 +4299,152 @@ width0pt\relax} \fi \newwrite\tocfile % Write an entry to the toc file, opening it if necessary. -% Called from @chapter, etc. We supply {\folio} at the end of the -% argument, which will end up as the last argument to the \...entry macro. -% -% Usage: \writetocentry{chap}{The Name of The Game}{{\the\chapno}} +% Called from @chapter, etc. +% +% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno} +% We append the current node name (if any) and page number as additional +% arguments for the \{chap,sec,...}entry macros which will eventually +% read this. The node name is used in the pdf outlines as the +% destination to jump to. +% % We open the .toc file for writing here instead of at @setfilename (or % any other fixed time) so that @contents can be anywhere in the document. +% But if #1 is `omit', then we don't do anything. This is used for the +% table of contents chapter openings themselves. % \newif\iftocfileopened +\def\omitkeyword{omit}% +% \def\writetocentry#1#2#3{% - \iftocfileopened\else - \immediate\openout\tocfile = \jobname.toc - \global\tocfileopenedtrue - \fi - % - \iflinks - \toks0 = {#2}% - \edef\temp{\write\tocfile{\realbackslash #1entry{\the\toks0}#3{\folio}}}% - \temp + \edef\writetoctype{#1}% + \ifx\writetoctype\omitkeyword \else + \iftocfileopened\else + \immediate\openout\tocfile = \jobname.toc + \global\tocfileopenedtrue + \fi + % + \iflinks + \toks0 = {#2}% + \toks2 = \expandafter{\lastnode}% + \edef\temp{\write\tocfile{\realbackslash #1entry{\the\toks0}{#3}% + {\the\toks2}{\noexpand\folio}}}% + \temp + \fi \fi % - % Tell \shipout to create a page destination if we're doing pdf, which - % will be the target of the links in the table of contents. We can't - % just do it on every page because the title pages are numbered 1 and - % 2 (the page numbers aren't printed), and so are the first two pages - % of the document. Thus, we'd have two destinations named `1', and - % two named `2'. - \ifpdf \pdfmakepagedesttrue \fi + % Tell \shipout to create a pdf destination on each page, if we're + % writing pdf. These are used in the table of contents. We can't + % just write one on every page because the title pages are numbered + % 1 and 2 (the page numbers aren't printed), and so are the first + % two pages of the document. Thus, we'd have two destinations named + % `1', and two named `2'. + \ifpdf \global\pdfmakepagedesttrue \fi } \newskip\contentsrightmargin \contentsrightmargin=1in \newcount\savepageno \newcount\lastnegativepageno \lastnegativepageno = -1 -% Finish up the main text and prepare to read what we've written -% to \tocfile. +% Prepare to read what we've written to \tocfile. % \def\startcontents#1{% - % If @setchapternewpage on, and @headings double, the contents should - % start on an odd page, unlike chapters. Thus, we maintain - % \contentsalignmacro in parallel with \pagealignmacro. - % From: Torbjorn Granlund <tege@matematik.su.se> - \contentsalignmacro - \immediate\closeout\tocfile - % - % Don't need to put `Contents' or `Short Contents' in the headline. - % It is abundantly clear what they are. - \unnumbchapmacro{#1}\def\thischapter{}% - \savepageno = \pageno - \begingroup % Set up to handle contents files properly. - \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11 - % We can't do this, because then an actual ^ in a section - % title fails, e.g., @chapter ^ -- exponentiation. --karl, 9jul97. - %\catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi - \raggedbottom % Worry more about breakpoints than the bottom. - \advance\hsize by -\contentsrightmargin % Don't use the full line length. - % - % Roman numerals for page numbers. - \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi + % If @setchapternewpage on, and @headings double, the contents should + % start on an odd page, unlike chapters. Thus, we maintain + % \contentsalignmacro in parallel with \pagealignmacro. + % From: Torbjorn Granlund <tege@matematik.su.se> + \contentsalignmacro + \immediate\closeout\tocfile + % + % Don't need to put `Contents' or `Short Contents' in the headline. + % It is abundantly clear what they are. + \def\thischapter{}% + \chapmacro{#1}{Yomitfromtoc}{}% + % + \savepageno = \pageno + \begingroup % Set up to handle contents files properly. + \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11 + % We can't do this, because then an actual ^ in a section + % title fails, e.g., @chapter ^ -- exponentiation. --karl, 9jul97. + %\catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi + \raggedbottom % Worry more about breakpoints than the bottom. + \advance\hsize by -\contentsrightmargin % Don't use the full line length. + % + % Roman numerals for page numbers. + \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi } % Normal (long) toc. \def\contents{% - \startcontents{\putwordTOC}% - \openin 1 \jobname.toc - \ifeof 1 \else - \closein 1 - \input \jobname.toc - \fi - \vfill \eject - \contentsalignmacro % in case @setchapternewpage odd is in effect - \pdfmakeoutlines - \endgroup - \lastnegativepageno = \pageno - \global\pageno = \savepageno + \startcontents{\putwordTOC}% + \openin 1 \jobname.toc + \ifeof 1 \else + \input \jobname.toc + \fi + \vfill \eject + \contentsalignmacro % in case @setchapternewpage odd is in effect + \ifeof 1 \else + \pdfmakeoutlines + \fi + \closein 1 + \endgroup + \lastnegativepageno = \pageno + \global\pageno = \savepageno } % And just the chapters. \def\summarycontents{% - \startcontents{\putwordShortTOC}% - % - \let\chapentry = \shortchapentry - \let\appendixentry = \shortappendixentry - \let\unnumbchapentry = \shortunnumberedentry - % We want a true roman here for the page numbers. - \secfonts - \let\rm=\shortcontrm \let\bf=\shortcontbf - \let\sl=\shortcontsl \let\tt=\shortconttt - \rm - \hyphenpenalty = 10000 - \advance\baselineskip by 1pt % Open it up a little. - \def\secentry ##1##2##3##4{} - \def\subsecentry ##1##2##3##4##5{} - \def\subsubsecentry ##1##2##3##4##5##6{} - \let\unnumbsecentry = \secentry - \let\unnumbsubsecentry = \subsecentry - \let\unnumbsubsubsecentry = \subsubsecentry - \openin 1 \jobname.toc - \ifeof 1 \else - \closein 1 - \input \jobname.toc - \fi - \vfill \eject - \contentsalignmacro % in case @setchapternewpage odd is in effect - \endgroup - \lastnegativepageno = \pageno - \global\pageno = \savepageno + \startcontents{\putwordShortTOC}% + % + \let\numchapentry = \shortchapentry + \let\appentry = \shortchapentry + \let\unnchapentry = \shortunnchapentry + % We want a true roman here for the page numbers. + \secfonts + \let\rm=\shortcontrm \let\bf=\shortcontbf + \let\sl=\shortcontsl \let\tt=\shortconttt + \rm + \hyphenpenalty = 10000 + \advance\baselineskip by 1pt % Open it up a little. + \def\numsecentry##1##2##3##4{} + \let\appsecentry = \numsecentry + \let\unnsecentry = \numsecentry + \let\numsubsecentry = \numsecentry + \let\appsubsecentry = \numsecentry + \let\unnsubsecentry = \numsecentry + \let\numsubsubsecentry = \numsecentry + \let\appsubsubsecentry = \numsecentry + \let\unnsubsubsecentry = \numsecentry + \openin 1 \jobname.toc + \ifeof 1 \else + \input \jobname.toc + \fi + \closein 1 + \vfill \eject + \contentsalignmacro % in case @setchapternewpage odd is in effect + \endgroup + \lastnegativepageno = \pageno + \global\pageno = \savepageno } \let\shortcontents = \summarycontents -\ifpdf - \pdfcatalog{/PageMode /UseOutlines}% -\fi +% Typeset the label for a chapter or appendix for the short contents. +% The arg is, e.g., `A' for an appendix, or `3' for a chapter. +% +\def\shortchaplabel#1{% + % This space should be enough, since a single number is .5em, and the + % widest letter (M) is 1em, at least in the Computer Modern fonts. + % But use \hss just in case. + % (This space doesn't include the extra space that gets added after + % the label; that gets put in by \shortchapentry above.) + % + % We'd like to right-justify chapter numbers, but that looks strange + % with appendix letters. And right-justifying numbers and + % left-justifying letters looks strange when there is less than 10 + % chapters. Have to read the whole toc once to know how many chapters + % there are before deciding ... + \hbox to 1em{#1\hss}% +} % These macros generate individual entries in the table of contents. % The first argument is the chapter or section name. @@ -4318,58 +4452,45 @@ width0pt\relax} \fi % The arguments in between are the chapter number, section number, ... % Chapters, in the main contents. -\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}} +\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}} % % Chapters, in the short toc. % See comments in \dochapentry re vbox and related settings. -\def\shortchapentry#1#2#3{% - \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#3\egroup}% +\def\shortchapentry#1#2#3#4{% + \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}% } % Appendices, in the main contents. -\def\appendixentry#1#2#3{% - \dochapentry{\appendixbox{\putwordAppendix{} #2}\labelspace#1}{#3}} -% -% Appendices, in the short toc. -\let\shortappendixentry = \shortchapentry - -% Typeset the label for a chapter or appendix for the short contents. -% The arg is, e.g., `Appendix A' for an appendix, or `3' for a chapter. -% We could simplify the code here by writing out an \appendixentry -% command in the toc file for appendices, instead of using \chapentry -% for both, but it doesn't seem worth it. -% -\newdimen\shortappendixwidth +% Need the word Appendix, and a fixed-size box. +% +\def\appendixbox#1{% + % We use M since it's probably the widest letter. + \setbox0 = \hbox{\putwordAppendix{} M}% + \hbox to \wd0{\putwordAppendix{} #1\hss}} % -\def\shortchaplabel#1{% - % This space should be enough, since a single number is .5em, and the - % widest letter (M) is 1em, at least in the Computer Modern fonts. - % But use \hss just in case. - % (This space doesn't include the extra space that gets added after - % the label; that gets put in by \shortchapentry above.) - \dimen0 = 1em - \hbox to \dimen0{#1\hss}% -} +\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}} % Unnumbered chapters. -\def\unnumbchapentry#1#2#3{\dochapentry{#1}{#3}} -\def\shortunnumberedentry#1#2#3{\tocentry{#1}{\doshortpageno\bgroup#3\egroup}} +\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}} +\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}} % Sections. -\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}} -\def\unnumbsecentry#1#2#3#4{\dosecentry{#1}{#4}} +\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}} +\let\appsecentry=\numsecentry +\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}} % Subsections. -\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}} -\def\unnumbsubsecentry#1#2#3#4#5{\dosubsecentry{#1}{#5}} +\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}} +\let\appsubsecentry=\numsubsecentry +\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}} % And subsubsections. -\def\subsubsecentry#1#2#3#4#5#6{% - \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} -\def\unnumbsubsubsecentry#1#2#3#4#5#6{\dosubsubsecentry{#1}{#6}} +\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}} +\let\appsubsubsecentry=\numsubsubsecentry +\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}} % This parameter controls the indentation of the various levels. -\newdimen\tocindent \tocindent = 3pc +\newdimen\tocindent \tocindent = 2pc % Now for the actual typesetting. In all these, #1 is the text and #2 is the % page number. @@ -4400,17 +4521,8 @@ width0pt\relax} \fi \tocentry{#1}{\dopageno\bgroup#2\egroup}% \endgroup} -% Final typesetting of a toc entry; we use the same \entry macro as for -% the index entries, but we want to suppress hyphenation here. (We -% can't do that in the \entry macro, since index entries might consist -% of hyphenated-identifiers-that-do-not-fit-on-a-line-and-nothing-else.) -\def\tocentry#1#2{\begingroup - \vskip 0pt plus1pt % allow a little stretch for the sake of nice page breaks - % Do not use \turnoffactive in these arguments. Since the toc is - % typeset in cmr, characters such as _ would come out wrong; we - % have to do the usual translation tricks. - \entry{#1}{#2}% -\endgroup} +% We use the same \entry macro as for the index entries. +\let\tocentry = \entry % Space between chapter (or whatever) number and the title. \def\labelspace{\hskip1em \relax} @@ -4420,8 +4532,8 @@ width0pt\relax} \fi \def\chapentryfonts{\secfonts \rm} \def\secentryfonts{\textfonts} -\let\subsecentryfonts = \textfonts -\let\subsubsecentryfonts = \textfonts +\def\subsecentryfonts{\textfonts} +\def\subsubsecentryfonts{\textfonts} \message{environments,} @@ -4448,10 +4560,10 @@ width0pt\relax} \fi % The text. (`r' is open on the right, `e' somewhat less so on the left.) \setbox0 = \hbox{\kern-.75pt \tensf error\kern-1.5pt} % -\global\setbox\errorbox=\hbox to \dimen0{\hfil +\setbox\errorbox=\hbox to \dimen0{\hfil \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. \advance\hsize by -2\dimen2 % Rules. - \vbox{ + \vbox{% \hrule height\dimen2 \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. @@ -4465,14 +4577,13 @@ width0pt\relax} \fi % One exception: @ is still an escape character, so that @end tex works. % But \@ or @@ will get a plain tex @ character. -\def\tex{\begingroup +\envdef\tex{% \catcode `\\=0 \catcode `\{=1 \catcode `\}=2 \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie \catcode `\%=14 \catcode `\+=\other \catcode `\"=\other - \catcode `\==\other \catcode `\|=\other \catcode `\<=\other \catcode `\>=\other @@ -4488,6 +4599,7 @@ width0pt\relax} \fi \let\!=\ptexexclam \let\i=\ptexi \let\indent=\ptexindent + \let\noindent=\ptexnoindent \let\{=\ptexlbrace \let\+=\tabalign \let\}=\ptexrbrace @@ -4498,10 +4610,11 @@ width0pt\relax} \fi \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% \def\@{@}% -\let\Etex=\endgroup} +} +% There is no need to define \Etex. % Define @lisp ... @end lisp. -% @lisp does a \begingroup so it can rebind things, +% @lisp environment forms a group so it can rebind things, % including the definition of @end lisp (which normally is erroneous). % Amount to narrow the margins by for @lisp. @@ -4512,19 +4625,6 @@ width0pt\relax} \fi % have any width. \def\lisppar{\null\endgraf} -% Make each space character in the input produce a normal interword -% space in the output. Don't allow a line break at this space, as this -% is used only in environments like @example, where each line of input -% should produce a line of output anyway. -% -{\obeyspaces % -\gdef\sepspaces{\obeyspaces\let =\tie}} - -% Define \obeyedspace to be our active space, whatever it is. This is -% for use in \parsearg. -{\sepspaces% -\global\let\obeyedspace= } - % This space is always present above and below environments. \newskip\envskipamount \envskipamount = 0pt @@ -4574,52 +4674,52 @@ width0pt\relax} \fi % \newskip\lskip\newskip\rskip -\def\cartouche{% -\par % can't be in the midst of a paragraph. -\begingroup - \lskip=\leftskip \rskip=\rightskip - \leftskip=0pt\rightskip=0pt %we want these *outside*. - \cartinner=\hsize \advance\cartinner by-\lskip - \advance\cartinner by-\rskip - \cartouter=\hsize - \advance\cartouter by 18.4pt % allow for 3pt kerns on either -% side, and for 6pt waste from -% each corner char, and rule thickness - \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip - % Flag to tell @lisp, etc., not to narrow margin. - \let\nonarrowing=\comment - \vbox\bgroup - \baselineskip=0pt\parskip=0pt\lineskip=0pt - \carttop - \hbox\bgroup - \hskip\lskip - \vrule\kern3pt - \vbox\bgroup - \hsize=\cartinner - \kern3pt - \begingroup - \baselineskip=\normbskip - \lineskip=\normlskip - \parskip=\normpskip - \vskip -\parskip +\envdef\cartouche{% + \ifhmode\par\fi % can't be in the midst of a paragraph. + \startsavinginserts + \lskip=\leftskip \rskip=\rightskip + \leftskip=0pt\rightskip=0pt % we want these *outside*. + \cartinner=\hsize \advance\cartinner by-\lskip + \advance\cartinner by-\rskip + \cartouter=\hsize + \advance\cartouter by 18.4pt % allow for 3pt kerns on either + % side, and for 6pt waste from + % each corner char, and rule thickness + \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip + % Flag to tell @lisp, etc., not to narrow margin. + \let\nonarrowing=\comment + \vbox\bgroup + \baselineskip=0pt\parskip=0pt\lineskip=0pt + \carttop + \hbox\bgroup + \hskip\lskip + \vrule\kern3pt + \vbox\bgroup + \kern3pt + \hsize=\cartinner + \baselineskip=\normbskip + \lineskip=\normlskip + \parskip=\normpskip + \vskip -\parskip + \comment % For explanation, see the end of \def\group. +} \def\Ecartouche{% - \endgroup - \kern3pt - \egroup - \kern3pt\vrule - \hskip\rskip - \egroup - \cartbot - \egroup -\endgroup -}} + \ifhmode\par\fi + \kern3pt + \egroup + \kern3pt\vrule + \hskip\rskip + \egroup + \cartbot + \egroup + \checkinserts +} % This macro is called at the beginning of all the @example variants, % inside a group. \def\nonfillstart{% \aboveenvbreak - \inENV % This group ends at the end of the body \hfuzz = 12pt % Don't be fussy \sepspaces % Make spaces be word-separators rather than space tokens. \let\par = \lisppar % don't ignore blank lines @@ -4632,103 +4732,71 @@ width0pt\relax} \fi \ifx\nonarrowing\relax \advance \leftskip by \lispnarrowing \exdentamount=\lispnarrowing - \let\exdent=\nofillexdent - \let\nonarrowing=\relax \fi + \let\exdent=\nofillexdent +} + +% We often define two environments, @foo and @smallfoo. +% Let's do it by one command: +\def\makedispenv #1#2{ + \expandafter\envdef\csname#1\endcsname{#2} + \expandafter\envdef\csname small#1\endcsname + {\smallexamplefonts \rm #2} + \expandafter\let\csname E#1\endcsname \afterenvbreak + \expandafter\let\csname Esmall#1\endcsname \afterenvbreak +} + +% And there are often two synonyms: +\def\maketwodispenvs #1#2#3{ + \makedispenv{#1}{#3} + \makedispenv{#2}{#3} } -% Define the \E... control sequence only if we are inside the particular -% environment, so the error checking in \end will work. +% @lisp: indented, narrowed, typewriter font; @example: same as @lisp. % -% To end an @example-like environment, we first end the paragraph (via -% \afterenvbreak's vertical glue), and then the group. That way we keep -% the zero \parskip that the environments set -- \parskip glue will be -% inserted at the beginning of the next paragraph in the document, after -% the environment. +% @smallexample and @smalllisp: use smaller fonts. +% Originally contributed by Pavel@xerox. % -\def\nonfillfinish{\afterenvbreak\endgroup} - -% @lisp: indented, narrowed, typewriter font. -\def\lisp{\begingroup +\maketwodispenvs {lisp}{example}{% \nonfillstart - \let\Elisp = \nonfillfinish \tt \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special. \gobble % eat return } -% @example: Same as @lisp. -\def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp} - -% @smallexample and @smalllisp: use smaller fonts. -% Originally contributed by Pavel@xerox. -\def\smalllisp{\begingroup - \def\Esmalllisp{\nonfillfinish\endgroup}% - \def\Esmallexample{\nonfillfinish\endgroup}% - \smallexamplefonts - \lisp -} -\let\smallexample = \smalllisp - - -% @display: same as @lisp except keep current font. +% @display/@smalldisplay: same as @lisp except keep current font. % -\def\display{\begingroup +\makedispenv {display}{% \nonfillstart - \let\Edisplay = \nonfillfinish \gobble } -% -% @smalldisplay: @display plus smaller fonts. -% -\def\smalldisplay{\begingroup - \def\Esmalldisplay{\nonfillfinish\endgroup}% - \smallexamplefonts \rm - \display -} -% @format: same as @display except don't narrow margins. +% @format/@smallformat: same as @display except don't narrow margins. +% @flushleft (same as @format). (Note: @smallflushleft not documeted.) % -\def\format{\begingroup - \let\nonarrowing = t +\maketwodispenvs {format}{flushleft}{% + \let\nonarrowing = t% \nonfillstart - \let\Eformat = \nonfillfinish \gobble } -% -% @smallformat: @format plus smaller fonts. -% -\def\smallformat{\begingroup - \def\Esmallformat{\nonfillfinish\endgroup}% - \smallexamplefonts \rm - \format -} - -% @flushleft (same as @format). -% -\def\flushleft{\begingroup \def\Eflushleft{\nonfillfinish\endgroup}\format} % @flushright. % -\def\flushright{\begingroup - \let\nonarrowing = t +\envdef\flushright{% + \let\nonarrowing = t% \nonfillstart - \let\Eflushright = \nonfillfinish \advance\leftskip by 0pt plus 1fill \gobble } +\let\Eflushright = \afterenvbreak % @quotation does normal linebreaking (hence we can't use \nonfillstart) % and narrows the margins. % -\def\quotation{% - \begingroup\inENV %This group ends at the end of the @quotation body +\envdef\quotation{% {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip \parindent=0pt - % We have retained a nonzero parskip for the environment, since we're - % doing normal filling. So to avoid extra space below the environment... - \def\Equotation{\parskip = 0pt \nonfillfinish}% % % @cartouche defines \nonarrowing to inhibit narrowing at next level down. \ifx\nonarrowing\relax @@ -4737,6 +4805,19 @@ width0pt\relax} \fi \exdentamount = \lispnarrowing \let\nonarrowing = \relax \fi + \parsearg\quotationlabel +} + +% We have retained a nonzero parskip for the environment, since we're +% doing normal filling. So to avoid extra space below the environment... +\def\Equotation{\parskip = 0pt \afterenvbreak} + +% If we're given an argument, typeset it in bold with a colon after. +\def\quotationlabel#1{% + \def\temp{#1}% + \ifx\temp\empty \else + {\bf #1: }% + \fi } @@ -4758,7 +4839,7 @@ width0pt\relax} \fi % % [Knuth] p. 380 \def\uncatcodespecials{% - \def\do##1{\catcode`##1=12}\dospecials} + \def\do##1{\catcode`##1=\other}\dospecials} % % [Knuth] pp. 380,381,391 % Disable Spanish ligatures ?` and !` of \tt font @@ -4806,6 +4887,8 @@ width0pt\relax} \fi } \endgroup \def\setupverbatim{% + \nonfillstart + \advance\leftskip by -\defbodyindent % Easiest (and conventionally used) font for verbatim \tt \def\par{\leavevmode\egroup\box0\endgraf}% @@ -4827,7 +4910,7 @@ width0pt\relax} \fi % % [Knuth] p. 382; only eat outer {} \begingroup - \catcode`[=1\catcode`]=2\catcode`\{=12\catcode`\}=12 + \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next] \endgroup % @@ -4844,13 +4927,6 @@ width0pt\relax} \fi % we need not redefine '\', '{' and '}'. % % Inspired by LaTeX's verbatim command set [latex.ltx] -%% Include LaTeX hack for completeness -- never know -%% \begingroup -%% \catcode`|=0 \catcode`[=1 -%% \catcode`]=2\catcode`\{=12\catcode`\}=12\catcode`\ =\active -%% \catcode`\\=12|gdef|doverbatim#1@end verbatim[ -%% #1|endgroup|def|Everbatim[]|end[verbatim]] -%% |endgroup % \begingroup \catcode`\ =\active @@ -4858,49 +4934,28 @@ width0pt\relax} \fi % ignore everything up to the first ^^M, that's the newline at the end % of the @verbatim input line itself. Otherwise we get an extra blank % line in the output. - \gdef\doverbatim#1^^M#2@end verbatim{#2\end{verbatim}}% + \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}% + % We really want {...\end verbatim} in the body of the macro, but + % without the active space; thus we have to use \xdef and \gobble. \endgroup % -\def\verbatim{% - \def\Everbatim{\nonfillfinish\endgroup}% - \begingroup - \nonfillstart - \advance\leftskip by -\defbodyindent - \begingroup\setupverbatim\doverbatim +\envdef\verbatim{% + \setupverbatim\doverbatim } +\let\Everbatim = \afterenvbreak + % @verbatiminclude FILE - insert text of file in verbatim environment. % -% Allow normal characters that we make active in the argument (a file name). -\def\verbatiminclude{% - \begingroup - \catcode`\\=\other - \catcode`~=\other - \catcode`^=\other - \catcode`_=\other - \catcode`|=\other - \catcode`<=\other - \catcode`>=\other - \catcode`+=\other - \parsearg\doverbatiminclude -} -\def\setupverbatiminclude{% - \begingroup - \nonfillstart - \advance\leftskip by -\defbodyindent - \begingroup\setupverbatim -} +\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude} % \def\doverbatiminclude#1{% - % Restore active chars for included file. - \endgroup - \begingroup - \let\value=\expandablevalue - \def\thisfile{#1}% - \expandafter\expandafter\setupverbatiminclude\input\thisfile - \endgroup - \nonfillfinish - \endgroup + {% + \makevalueexpandable + \setupverbatim + \input #1 + \afterenvbreak + }% } % @copying ... @end copying. @@ -4975,581 +5030,335 @@ width0pt\relax} \fi \message{defuns,} % @defun etc. -% Allow user to change definition object font (\df) internally -\def\setdeffont#1 {\csname DEF#1\endcsname} - \newskip\defbodyindent \defbodyindent=.4in \newskip\defargsindent \defargsindent=50pt \newskip\deflastargmargin \deflastargmargin=18pt -\newcount\parencount - -% We want ()&[] to print specially on the defun line. -% -\def\activeparens{% - \catcode`\(=\active \catcode`\)=\active - \catcode`\&=\active - \catcode`\[=\active \catcode`\]=\active -} - -% Make control sequences which act like normal parenthesis chars. -\let\lparen = ( \let\rparen = ) - -{\activeparens % Now, smart parens don't turn on until &foo (see \amprm) - -% Be sure that we always have a definition for `(', etc. For example, -% if the fn name has parens in it, \boldbrax will not be in effect yet, -% so TeX would otherwise complain about undefined control sequence. -\global\let(=\lparen \global\let)=\rparen -\global\let[=\lbrack \global\let]=\rbrack - -\gdef\functionparens{\boldbrax\let&=\amprm\parencount=0 } -\gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} -% This is used to turn on special parens -% but make & act ordinary (given that it's active). -\gdef\boldbraxnoamp{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb\let&=\ampnr} - -% Definitions of (, ) and & used in args for functions. -% This is the definition of ( outside of all parentheses. -\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested - \global\advance\parencount by 1 -} -% -% This is the definition of ( when already inside a level of parens. -\gdef\opnested{\char`\(\global\advance\parencount by 1 } -% -\gdef\clrm{% Print a paren in roman if it is taking us back to depth of 0. - % also in that case restore the outer-level definition of (. - \ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi - \global\advance \parencount by -1 } -% If we encounter &foo, then turn on ()-hacking afterwards -\gdef\amprm#1 {{\rm\}\let(=\oprm \let)=\clrm\ } -% -\gdef\normalparens{\boldbrax\let&=\ampnr} -} % End of definition inside \activeparens -%% These parens (in \boldbrax) actually are a little bolder than the -%% contained text. This is especially needed for [ and ] -\def\opnr{{\sf\char`\(}\global\advance\parencount by 1 } -\def\clnr{{\sf\char`\)}\global\advance\parencount by -1 } -\let\ampnr = \& -\def\lbrb{{\bf\char`\[}} -\def\rbrb{{\bf\char`\]}} - -% Active &'s sneak into the index arguments, so make sure it's defined. -{ - \catcode`& = \active - \global\let& = \ampnr -} - -% \defname, which formats the name of the @def (not the args). -% #1 is the function name. -% #2 is the type of definition, such as "Function". -% -\def\defname#1#2{% - % How we'll output the type name. Putting it in brackets helps - % distinguish it from the body text that may end up on the next line - % just below it. - \ifempty{#2}% - \def\defnametype{}% +% Start the processing of @deffn: +\def\startdefun{% + \ifnum\lastpenalty<10000 + \medbreak \else - \def\defnametype{[\rm #2]}% + % If there are two @def commands in a row, we'll have a \nobreak, + % which is there to keep the function description together with its + % header. But if there's nothing but headers, we need to allow a + % break somewhere. Check for penalty 10002 (inserted by + % \defargscommonending) instead of 10000, since the sectioning + % commands insert a \penalty10000, and we don't want to allow a break + % between a section heading and a defun. + \ifnum\lastpenalty=10002 \penalty2000 \fi + % + % Similarly, after a section heading, do not allow a break. + % But do insert the glue. + \medskip % preceded by discardable penalty, so not a breakpoint \fi % - % Get the values of \leftskip and \rightskip as they were outside the @def... - \dimen2=\leftskip - \advance\dimen2 by -\defbodyindent - % - % Figure out values for the paragraph shape. - \setbox0=\hbox{\hskip \deflastargmargin{\defnametype}}% - \dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line - \dimen1=\hsize \advance \dimen1 by -\defargsindent % size for continuations - \parshape 2 0in \dimen0 \defargsindent \dimen1 - % - % Output arg 2 ("Function" or some such) but stuck inside a box of - % width 0 so it does not interfere with linebreaking. - \noindent - % - {% Adjust \hsize to exclude the ambient margins, - % so that \rightline will obey them. - \advance \hsize by -\dimen2 - \dimen3 = 0pt % was -1.25pc - \rlap{\rightline{\defnametype\kern\dimen3}}% - }% - % - % Allow all lines to be underfull without complaint: - \tolerance=10000 \hbadness=10000 - \advance\leftskip by -\defbodyindent - \exdentamount=\defbodyindent - {\df #1}\enskip % output function name - % \defunargs will be called next to output the arguments, if any. -} - -% Common pieces to start any @def... -% #1 is the \E... control sequence to end the definition (which we define). -% #2 is the \...x control sequence (which our caller defines). -% #3 is the control sequence to process the header, such as \defunheader. -% -\def\parsebodycommon#1#2#3{% - \begingroup\inENV - % If there are two @def commands in a row, we'll have a \nobreak, - % which is there to keep the function description together with its - % header. But if there's nothing but headers, we want to allow a - % break after all. Check for penalty 10002 (inserted by - % \defargscommonending) instead of 10000, since the sectioning - % commands insert a \penalty10000, and we don't want to allow a break - % between a section heading and a defun. - \ifnum\lastpenalty=10002 \penalty0 \fi - \medbreak - % - % Define the \E... end token that this defining construct specifies - % so that it will exit this group. - \def#1{\endgraf\endgroup\medbreak}% - % \parindent=0in \advance\leftskip by \defbodyindent \exdentamount=\defbodyindent } -% Common part of the \...x definitions. -% -\def\defxbodycommon{% - % As with \parsebodycommon above, allow line break if we have multiple - % x headers in a row. It's not a great place, though. - \ifnum\lastpenalty=10000 \penalty1000 \fi +\def\dodefunx#1{% + % First, check whether we are in the right environment: + \checkenv#1% + % + % As above, allow line break if we have multiple x headers in a row. + % It's not a great place, though. + \ifnum\lastpenalty=10002 \penalty3000 \fi % - \begingroup\obeylines + % And now, it's time to reuse the body of the original defun: + \expandafter\gobbledefun#1% } +\def\gobbledefun#1\startdefun{} -% Process body of @defun, @deffn, @defmac, etc. +% \printdefunline \deffnheader{text} % -\def\defparsebody#1#2#3{% - \parsebodycommon{#1}{#2}{#3}% - \def#2{\defxbodycommon \activeparens \spacesplit#3}% - \catcode\equalChar=\active - \begingroup\obeylines\activeparens - \spacesplit#3% +\def\printdefunline#1#2{% + \begingroup + % call \deffnheader: + #1#2 \endheader + % common ending: + \interlinepenalty = 10000 + \advance\rightskip by 0pt plus 1fil + \endgraf + \nobreak\vskip -\parskip + \penalty 10002 % signal to \startdefun and \dodefunx + % Some of the @defun-type tags do not enable magic parentheses, + % rendering the following check redundant. But we don't optimize. + \checkparencounts + \endgroup } -% #1, #2, #3 are the common arguments (see \parsebodycommon above). -% #4, delimited by the space, is the class name. -% -\def\defmethparsebody#1#2#3#4 {% - \parsebodycommon{#1}{#2}{#3}% - \def#2##1 {\defxbodycommon \activeparens \spacesplit{#3{##1}}}% - \begingroup\obeylines\activeparens - % The \empty here prevents misinterpretation of a construct such as - % @deffn {whatever} {Enharmonic comma} - % See comments at \deftpparsebody, although in our case we don't have - % to remove the \empty afterwards, since it is empty. - \spacesplit{#3{#4}}\empty -} +\def\Edefun{\endgraf\medbreak} -% Used for @deftypemethod and @deftypeivar. -% #1, #2, #3 are the common arguments (see \defparsebody). -% #4, delimited by a space, is the class name. -% #5 is the method's return type. +% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn; +% the only thing remainnig is to define \deffnheader. % -\def\deftypemethparsebody#1#2#3#4 #5 {% - \parsebodycommon{#1}{#2}{#3}% - \def#2##1 ##2 {\defxbodycommon \activeparens \spacesplit{#3{##1}{##2}}}% - \begingroup\obeylines\activeparens - \spacesplit{#3{#4}{#5}}% +\def\makedefun#1{% + \expandafter\let\csname E#1\endcsname = \Edefun + \edef\temp{\noexpand\domakedefun + \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}% + \temp } -% Used for @deftypeop. The change from \deftypemethparsebody is an -% extra argument at the beginning which is the `category', instead of it -% being the hardwired string `Method' or `Instance Variable'. We have -% to account for this both in the \...x definition and in parsing the -% input at hand. Thus also need a control sequence (passed as #5) for -% the \E... definition to assign the category name to. +% \domakedefun \deffn \deffnx \deffnheader % -\def\deftypeopparsebody#1#2#3#4#5 #6 {% - \parsebodycommon{#1}{#2}{#3}% - \def#2##1 ##2 ##3 {\def#4{##1}% - \defxbodycommon \activeparens \spacesplit{#3{##2}{##3}}}% - \begingroup\obeylines\activeparens - \spacesplit{#3{#5}{#6}}% -} - -% For @defop. -\def\defopparsebody #1#2#3#4#5 {% - \parsebodycommon{#1}{#2}{#3}% - \def#2##1 ##2 {\def#4{##1}% - \defxbodycommon \activeparens \spacesplit{#3{##2}}}% - \begingroup\obeylines\activeparens - \spacesplit{#3{#5}}% -} - -% These parsing functions are similar to the preceding ones -% except that they do not make parens into active characters. -% These are used for "variables" since they have no arguments. +% Define \deffn and \deffnx, without parameters. +% \deffnheader has to be defined explicitly. % -\def\defvarparsebody #1#2#3{% - \parsebodycommon{#1}{#2}{#3}% - \def#2{\defxbodycommon \spacesplit#3}% - \catcode\equalChar=\active - \begingroup\obeylines - \spacesplit#3% +\def\domakedefun#1#2#3{% + \envdef#1{% + \startdefun + \parseargusing\activeparens{\printdefunline#3}% + }% + \def#2{\dodefunx#1}% + \def#3% } -% @defopvar. -\def\defopvarparsebody #1#2#3#4#5 {% - \parsebodycommon{#1}{#2}{#3}% - \def#2##1 ##2 {\def#4{##1}% - \defxbodycommon \spacesplit{#3{##2}}}% - \begingroup\obeylines - \spacesplit{#3{#5}}% -} +%%% Untyped functions: -\def\defvrparsebody#1#2#3#4 {% - \parsebodycommon{#1}{#2}{#3}% - \def#2##1 {\defxbodycommon \spacesplit{#3{##1}}}% - \begingroup\obeylines - \spacesplit{#3{#4}}% -} +% @deffn category name args +\makedefun{deffn}{\deffngeneral{}} -% This loses on `@deftp {Data Type} {struct termios}' -- it thinks the -% type is just `struct', because we lose the braces in `{struct -% termios}' when \spacesplit reads its undelimited argument. Sigh. -% \let\deftpparsebody=\defvrparsebody -% -% So, to get around this, we put \empty in with the type name. That -% way, TeX won't find exactly `{...}' as an undelimited argument, and -% won't strip off the braces. -% -\def\deftpparsebody #1#2#3#4 {% - \parsebodycommon{#1}{#2}{#3}% - \def#2##1 {\defxbodycommon \spacesplit{#3{##1}}}% - \begingroup\obeylines - \spacesplit{\parsetpheaderline{#3{#4}}}\empty -} - -% Fine, but then we have to eventually remove the \empty *and* the -% braces (if any). That's what this does. -% -\def\removeemptybraces\empty#1\relax{#1} +% @deffn category class name args +\makedefun{defop}#1 {\defopon{#1\ \putwordon}} -% After \spacesplit has done its work, this is called -- #1 is the final -% thing to call, #2 the type name (which starts with \empty), and #3 -% (which might be empty) the arguments. -% -\def\parsetpheaderline#1#2#3{% - #1{\removeemptybraces#2\relax}{#3}% -}% +% \defopon {category on}class name args +\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } -% Split up #2 (the rest of the input line) at the first space token. -% call #1 with two arguments: -% the first is all of #2 before the space token, -% the second is all of #2 after that space token. -% If #2 contains no space token, all of it is passed as the first arg -% and the second is passed as empty. +% \deffngeneral {subind}category name args % -{\obeylines % - \gdef\spacesplit#1#2^^M{\endgroup\spacesplitx{#1}#2 \relax\spacesplitx}% - \long\gdef\spacesplitx#1#2 #3#4\spacesplitx{% - \ifx\relax #3% - #1{#2}{}% - \else % - #1{#2}{#3#4}% - \fi}% +\def\deffngeneral#1#2 #3 #4\endheader{% + % Remember that \dosubin{fn}{xxx}{} is equivalent to \doind{fn}{xxx}. + \dosubind{fn}{\code{#3}}{#1}% + \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}% } -% Define @defun. +%%% Typed functions: -% This is called to end the arguments processing for all the @def... commands. -% -\def\defargscommonending{% - \interlinepenalty = 10000 - \advance\rightskip by 0pt plus 1fil - \endgraf - \nobreak\vskip -\parskip - \penalty 10002 % signal to \parsebodycommon. -} +% @deftypefn category type name args +\makedefun{deftypefn}{\deftypefngeneral{}} + +% @deftypeop category class type name args +\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}} -% This expands the args and terminates the paragraph they comprise. +% \deftypeopon {category on}class type name args +\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } + +% \deftypefngeneral {subind}category type name args % -\def\defunargs#1{\functionparens \sl -% Expand, preventing hyphenation at `-' chars. -% Note that groups don't affect changes in \hyphenchar. -% Set the font temporarily and use \font in case \setfont made \tensl a macro. -{\tensl\hyphenchar\font=0}% -#1% -{\tensl\hyphenchar\font=45}% -\ifnum\parencount=0 \else \errmessage{Unbalanced parentheses in @def}\fi% - \defargscommonending +\def\deftypefngeneral#1#2 #3 #4 #5\endheader{% + \dosubind{fn}{\code{#4}}{#1}% + \defname{#2}{#3}{#4}\defunargs{#5\unskip}% } -\def\deftypefunargs #1{% -% Expand, preventing hyphenation at `-' chars. -% Note that groups don't affect changes in \hyphenchar. -% Use \boldbraxnoamp, not \functionparens, so that & is not special. -\boldbraxnoamp -\tclose{#1}% avoid \code because of side effects on active chars - \defargscommonending -} +%%% Typed variables: -% Do complete processing of one @defun or @defunx line already parsed. +% @deftypevr category type var args +\makedefun{deftypevr}{\deftypecvgeneral{}} -% @deffn Command forward-char nchars +% @deftypecv category class type var args +\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}} -\def\deffn{\defmethparsebody\Edeffn\deffnx\deffnheader} +% \deftypecvof {category of}class type var args +\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} } -\def\deffnheader #1#2#3{\doind {fn}{\code{#2}}% -\begingroup\defname {#2}{#1}\defunargs{#3}\endgroup % -\catcode\equalChar=\other % Turn off change made in \defparsebody +% \deftypecvgeneral {subind}category type var args +% +\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{% + \dosubind{vr}{\code{#4}}{#1}% + \defname{#2}{#3}{#4}\defunargs{#5\unskip}% } -% @defun == @deffn Function - -\def\defun{\defparsebody\Edefun\defunx\defunheader} +%%% Untyped variables: -\def\defunheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index -\begingroup\defname {#1}{\putwordDeffunc}% -\defunargs {#2}\endgroup % -\catcode\equalChar=\other % Turn off change made in \defparsebody -} +% @defvr category var args +\makedefun{defvr}#1 {\deftypevrheader{#1} {} } -% @deftypefun int foobar (int @var{foo}, float @var{bar}) +% @defcv category class var args +\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}} -\def\deftypefun{\defparsebody\Edeftypefun\deftypefunx\deftypefunheader} +% \defcvof {category of}class var args +\def\defcvof#1#2 {\deftypecvof{#1}#2 {} } -% #1 is the data type. #2 is the name and args. -\def\deftypefunheader #1#2{\deftypefunheaderx{#1}#2 \relax} -% #1 is the data type, #2 the name, #3 the args. -\def\deftypefunheaderx #1#2 #3\relax{% -\doind {fn}{\code{#2}}% Make entry in function index -\begingroup\defname {\defheaderxcond#1\relax$.$#2}{\putwordDeftypefun}% -\deftypefunargs {#3}\endgroup % -\catcode\equalChar=\other % Turn off change made in \defparsebody +%%% Type: +% @deftp category name args +\makedefun{deftp}#1 #2 #3\endheader{% + \doind{tp}{\code{#2}}% + \defname{#1}{}{#2}\defunargs{#3\unskip}% } -% @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) - -\def\deftypefn{\defmethparsebody\Edeftypefn\deftypefnx\deftypefnheader} +% Remaining @defun-like shortcuts: +\makedefun{defun}{\deffnheader{\putwordDeffunc} } +\makedefun{defmac}{\deffnheader{\putwordDefmac} } +\makedefun{defspec}{\deffnheader{\putwordDefspec} } +\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} } +\makedefun{defvar}{\defvrheader{\putwordDefvar} } +\makedefun{defopt}{\defvrheader{\putwordDefopt} } +\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} } +\makedefun{defmethod}{\defopon\putwordMethodon} +\makedefun{deftypemethod}{\deftypeopon\putwordMethodon} +\makedefun{defivar}{\defcvof\putwordInstanceVariableof} +\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof} -% \defheaderxcond#1\relax$.$ -% puts #1 in @code, followed by a space, but does nothing if #1 is null. -\def\defheaderxcond#1#2$.${\ifx#1\relax\else\code{#1#2} \fi} - -% #1 is the classification. #2 is the data type. #3 is the name and args. -\def\deftypefnheader #1#2#3{\deftypefnheaderx{#1}{#2}#3 \relax} -% #1 is the classification, #2 the data type, #3 the name, #4 the args. -\def\deftypefnheaderx #1#2#3 #4\relax{% -\doind {fn}{\code{#3}}% Make entry in function index -\begingroup -\normalparens % notably, turn off `&' magic, which prevents -% at least some C++ text from working -\defname {\defheaderxcond#2\relax$.$#3}{#1}% -\deftypefunargs {#4}\endgroup % -\catcode\equalChar=\other % Turn off change made in \defparsebody +% \defname, which formats the name of the @def (not the args). +% #1 is the category, such as "Function". +% #2 is the return type, if any. +% #3 is the function name. +% +% We are followed by (but not passed) the arguments, if any. +% +\def\defname#1#2#3{% + % Get the values of \leftskip and \rightskip as they were outside the @def... + \advance\leftskip by -\defbodyindent + % + % How we'll format the type name. Putting it in brackets helps + % distinguish it from the body text that may end up on the next line + % just below it. + \def\temp{#1}% + \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi} + % + % Figure out line sizes for the paragraph shape. + % The first line needs space for \box0; but if \rightskip is nonzero, + % we need only space for the part of \box0 which exceeds it: + \dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip + % The continuations: + \dimen2=\hsize \advance\dimen2 by -\defargsindent + % (plain.tex says that \dimen1 should be used only as global.) + \parshape 2 0in \dimen0 \defargsindent \dimen2 + % + % Put the type name to the right margin. + \noindent + \hbox to 0pt{% + \hfil\box0 \kern-\hsize + % \hsize has to be shortened this way: + \kern\leftskip + % Intentionally do not respect \rightskip, since we need the space. + }% + % + % Allow all lines to be underfull without complaint: + \tolerance=10000 \hbadness=10000 + \exdentamount=\defbodyindent + {% + % defun fonts. We use typewriter by default (used to be bold) because: + % . we're printing identifiers, they should be in tt in principle. + % . in languages with many accents, such as Czech or French, it's + % common to leave accents off identifiers. The result looks ok in + % tt, but exceedingly strange in rm. + % . we don't want -- and --- to be treated as ligatures. + % . this still does not fix the ?` and !` ligatures, but so far no + % one has made identifiers using them :). + \df \tt + \def\temp{#2}% return value type + \ifx\temp\empty\else \tclose{\temp} \fi + #3% output function name + }% + {\rm\enskip}% hskip 0.5 em of \tenrm + % + \boldbrax + % arguments will be output next, if any. +} + +% Print arguments in slanted typewriter, prevent hyphenation at `-' chars. +% +\def\defunargs#1{% + % use sl by default (not ttsl), inconsistently with using tt for the + % name. This is because literal text is sometimes needed in the + % argument list (groff manual), and ttsl and tt are not very + % distinguishable. + % tt for the names. + \df \sl \hyphenchar\font=0 + % On the other hand, if an argument has two dashes (for instance), we + % want a way to get ttsl. Let's try @var for that. + \let\var=\ttslanted + #1% + \sl\hyphenchar\font=45 } -% @defmac == @deffn Macro - -\def\defmac{\defparsebody\Edefmac\defmacx\defmacheader} - -\def\defmacheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index -\begingroup\defname {#1}{\putwordDefmac}% -\defunargs {#2}\endgroup % -\catcode\equalChar=\other % Turn off change made in \defparsebody +% We want ()&[] to print specially on the defun line. +% +\def\activeparens{% + \catcode`\(=\active \catcode`\)=\active + \catcode`\[=\active \catcode`\]=\active + \catcode`\&=\active } -% @defspec == @deffn Special Form +% Make control sequences which act like normal parenthesis chars. +\let\lparen = ( \let\rparen = ) -\def\defspec{\defparsebody\Edefspec\defspecx\defspecheader} +% Be sure that we always have a definition for `(', etc. For example, +% if the fn name has parens in it, \boldbrax will not be in effect yet, +% so TeX would otherwise complain about undefined control sequence. +{ + \activeparens + \global\let(=\lparen \global\let)=\rparen + \global\let[=\lbrack \global\let]=\rbrack + \global\let& = \& -\def\defspecheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index -\begingroup\defname {#1}{\putwordDefspec}% -\defunargs {#2}\endgroup % -\catcode\equalChar=\other % Turn off change made in \defparsebody + \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} + \gdef\magicamp{\let&=\amprm} } -% @defop CATEGORY CLASS OPERATION ARG... -% -\def\defop #1 {\def\defoptype{#1}% -\defopparsebody\Edefop\defopx\defopheader\defoptype} -% -\def\defopheader#1#2#3{% - \dosubind{fn}{\code{#2}}{\putwordon\ \code{#1}}% function index entry - \begingroup - \defname{#2}{\defoptype\ \putwordon\ #1}% - \defunargs{#3}% - \endgroup -} +\newcount\parencount -% @deftypeop CATEGORY CLASS TYPE OPERATION ARG... -% -\def\deftypeop #1 {\def\deftypeopcategory{#1}% - \deftypeopparsebody\Edeftypeop\deftypeopx\deftypeopheader - \deftypeopcategory} -% -% #1 is the class name, #2 the data type, #3 the operation name, #4 the args. -\def\deftypeopheader#1#2#3#4{% - \dosubind{fn}{\code{#3}}{\putwordon\ \code{#1}}% entry in function index - \begingroup - \defname{\defheaderxcond#2\relax$.$#3} - {\deftypeopcategory\ \putwordon\ \code{#1}}% - \deftypefunargs{#4}% - \endgroup +% If we encounter &foo, then turn on ()-hacking afterwards +\newif\ifampseen +\def\amprm#1 {\ampseentrue{\bf\ }} + +\def\parenfont{% + \ifampseen + % At the first level, print parens in roman, + % otherwise use the default font. + \ifnum \parencount=1 \rm \fi + \else + % The \sf parens (in \boldbrax) actually are a little bolder than + % the contained text. This is especially needed for [ and ] . + \sf + \fi } - -% @deftypemethod CLASS TYPE METHOD ARG... -% -\def\deftypemethod{% - \deftypemethparsebody\Edeftypemethod\deftypemethodx\deftypemethodheader} -% -% #1 is the class name, #2 the data type, #3 the method name, #4 the args. -\def\deftypemethodheader#1#2#3#4{% - \dosubind{fn}{\code{#3}}{\putwordon\ \code{#1}}% entry in function index - \begingroup - \defname{\defheaderxcond#2\relax$.$#3}{\putwordMethodon\ \code{#1}}% - \deftypefunargs{#4}% - \endgroup +\def\infirstlevel#1{% + \ifampseen + \ifnum\parencount=1 + #1% + \fi + \fi } +\def\bfafterword#1 {#1 \bf} -% @deftypeivar CLASS TYPE VARNAME -% -\def\deftypeivar{% - \deftypemethparsebody\Edeftypeivar\deftypeivarx\deftypeivarheader} -% -% #1 is the class name, #2 the data type, #3 the variable name. -\def\deftypeivarheader#1#2#3{% - \dosubind{vr}{\code{#3}}{\putwordof\ \code{#1}}% entry in variable index - \begingroup - \defname{\defheaderxcond#2\relax$.$#3} - {\putwordInstanceVariableof\ \code{#1}}% - \defvarargs{#3}% - \endgroup +\def\opnr{% + \global\advance\parencount by 1 + {\parenfont(}% + \infirstlevel \bfafterword } - -% @defmethod == @defop Method -% -\def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader} -% -% #1 is the class name, #2 the method name, #3 the args. -\def\defmethodheader#1#2#3{% - \dosubind{fn}{\code{#2}}{\putwordon\ \code{#1}}% entry in function index - \begingroup - \defname{#2}{\putwordMethodon\ \code{#1}}% - \defunargs{#3}% - \endgroup +\def\clnr{% + {\parenfont)}% + \infirstlevel \sl + \global\advance\parencount by -1 } -% @defcv {Class Option} foo-class foo-flag - -\def\defcv #1 {\def\defcvtype{#1}% -\defopvarparsebody\Edefcv\defcvx\defcvarheader\defcvtype} - -\def\defcvarheader #1#2#3{% - \dosubind{vr}{\code{#2}}{\putwordof\ \code{#1}}% variable index entry - \begingroup - \defname{#2}{\defcvtype\ \putwordof\ #1}% - \defvarargs{#3}% - \endgroup +\newcount\brackcount +\def\lbrb{% + \global\advance\brackcount by 1 + {\bf[}% } - -% @defivar CLASS VARNAME == @defcv {Instance Variable} CLASS VARNAME -% -\def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader} -% -\def\defivarheader#1#2#3{% - \dosubind{vr}{\code{#2}}{\putwordof\ \code{#1}}% entry in var index - \begingroup - \defname{#2}{\putwordInstanceVariableof\ #1}% - \defvarargs{#3}% - \endgroup +\def\rbrb{% + {\bf]}% + \global\advance\brackcount by -1 } -% @defvar -% First, define the processing that is wanted for arguments of @defvar. -% This is actually simple: just print them in roman. -% This must expand the args and terminate the paragraph they make up -\def\defvarargs #1{\normalparens #1% - \defargscommonending +\def\checkparencounts{% + \ifnum\parencount=0 \else \badparencount \fi + \ifnum\brackcount=0 \else \badbrackcount \fi } - -% @defvr Counter foo-count - -\def\defvr{\defvrparsebody\Edefvr\defvrx\defvrheader} - -\def\defvrheader #1#2#3{\doind {vr}{\code{#2}}% -\begingroup\defname {#2}{#1}\defvarargs{#3}\endgroup} - -% @defvar == @defvr Variable - -\def\defvar{\defvarparsebody\Edefvar\defvarx\defvarheader} - -\def\defvarheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index -\begingroup\defname {#1}{\putwordDefvar}% -\defvarargs {#2}\endgroup % +\def\badparencount{% + \errmessage{Unbalanced parentheses in @def}% + \global\parencount=0 } - -% @defopt == @defvr {User Option} - -\def\defopt{\defvarparsebody\Edefopt\defoptx\defoptheader} - -\def\defoptheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index -\begingroup\defname {#1}{\putwordDefopt}% -\defvarargs {#2}\endgroup % +\def\badbrackcount{% + \errmessage{Unbalanced square braces in @def}% + \global\brackcount=0 } -% @deftypevar int foobar - -\def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader} - -% #1 is the data type. #2 is the name, perhaps followed by text that -% is actually part of the data type, which should not be put into the index. -\def\deftypevarheader #1#2{% -\dovarind#2 \relax% Make entry in variables index -\begingroup\defname {\defheaderxcond#1\relax$.$#2}{\putwordDeftypevar}% - \defargscommonending -\endgroup} -\def\dovarind#1 #2\relax{\doind{vr}{\code{#1}}} - -% @deftypevr {Global Flag} int enable - -\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader} - -\def\deftypevrheader #1#2#3{\dovarind#3 \relax% -\begingroup\defname {\defheaderxcond#2\relax$.$#3}{#1} - \defargscommonending -\endgroup} - -% Now define @deftp -% Args are printed in bold, a slight difference from @defvar. - -\def\deftpargs #1{\bf \defvarargs{#1}} - -% @deftp Class window height width ... - -\def\deftp{\deftpparsebody\Edeftp\deftpx\deftpheader} - -\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}% -\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup} - -% These definitions are used if you use @defunx (etc.) -% anywhere other than immediately after a @defun or @defunx. -% -\def\defcvx#1 {\errmessage{@defcvx in invalid context}} -\def\deffnx#1 {\errmessage{@deffnx in invalid context}} -\def\defivarx#1 {\errmessage{@defivarx in invalid context}} -\def\defmacx#1 {\errmessage{@defmacx in invalid context}} -\def\defmethodx#1 {\errmessage{@defmethodx in invalid context}} -\def\defoptx #1 {\errmessage{@defoptx in invalid context}} -\def\defopx#1 {\errmessage{@defopx in invalid context}} -\def\defspecx#1 {\errmessage{@defspecx in invalid context}} -\def\deftpx#1 {\errmessage{@deftpx in invalid context}} -\def\deftypefnx#1 {\errmessage{@deftypefnx in invalid context}} -\def\deftypefunx#1 {\errmessage{@deftypefunx in invalid context}} -\def\deftypeivarx#1 {\errmessage{@deftypeivarx in invalid context}} -\def\deftypemethodx#1 {\errmessage{@deftypemethodx in invalid context}} -\def\deftypeopx#1 {\errmessage{@deftypeopx in invalid context}} -\def\deftypevarx#1 {\errmessage{@deftypevarx in invalid context}} -\def\deftypevrx#1 {\errmessage{@deftypevrx in invalid context}} -\def\defunx#1 {\errmessage{@defunx in invalid context}} -\def\defvarx#1 {\errmessage{@defvarx in invalid context}} -\def\defvrx#1 {\errmessage{@defvrx in invalid context}} - \message{macros,} % @macro. @@ -5557,28 +5366,33 @@ width0pt\relax} \fi % To do this right we need a feature of e-TeX, \scantokens, % which we arrange to emulate with a temporary file in ordinary TeX. \ifx\eTeXversion\undefined - \newwrite\macscribble - \def\scanmacro#1{% - \begingroup \newlinechar`\^^M - % Undo catcode changes of \startcontents and \doprintindex - \catcode`\@=0 \catcode`\\=\other \escapechar=`\@ - % Append \endinput to make sure that TeX does not see the ending newline. - \toks0={#1\endinput}% - \immediate\openout\macscribble=\jobname.tmp - \immediate\write\macscribble{\the\toks0}% - \immediate\closeout\macscribble - \let\xeatspaces\eatspaces - \input \jobname.tmp - \endgroup -} -\else -\def\scanmacro#1{% -\begingroup \newlinechar`\^^M -% Undo catcode changes of \startcontents and \doprintindex -\catcode`\@=0 \catcode`\\=\other \escapechar=`\@ -\let\xeatspaces\eatspaces\scantokens{#1\endinput}\endgroup} + \newwrite\macscribble + \def\scantokens#1{% + \toks0={#1\endinput}% + \immediate\openout\macscribble=\jobname.tmp + \immediate\write\macscribble{\the\toks0}% + \immediate\closeout\macscribble + \input \jobname.tmp + } \fi +\def\scanmacro#1{% + \begingroup + \newlinechar`\^^M + \let\xeatspaces\eatspaces + % Undo catcode changes of \startcontents and \doprintindex + \catcode`\@=0 \catcode`\\=\other \escapechar=`\@ + % ... and \example + \spaceisspace + % + % Append \endinput to make sure that TeX does not see the ending newline. + % + % I've verified that it is necessary both for e-TeX and for ordinary TeX + % --kasal, 29nov03 + \scantokens{#1\endinput}% + \endgroup +} + \newcount\paramno % Count of parameters \newtoks\macname % Macro name \newif\ifrecursive % Is it recursive? @@ -5586,7 +5400,7 @@ width0pt\relax} \fi % \do\macro1\do\macro2... % Utility routines. -% Thisdoes \let #1 = #2, except with \csnames. +% This does \let #1 = #2, except with \csnames. \def\cslet#1#2{% \expandafter\expandafter \expandafter\let @@ -5683,8 +5497,7 @@ width0pt\relax} \fi \else \expandafter\parsemacbody \fi} -\def\unmacro{\parsearg\dounmacro} -\def\dounmacro#1{% +\parseargdef\unmacro{% \if1\csname ismacro.#1\endcsname \global\cslet{#1}{macsave.#1}% \global\expandafter\let \csname ismacro.#1\endcsname=0% @@ -5834,16 +5647,18 @@ width0pt\relax} \fi % @alias. % We need some trickery to remove the optional spaces around the equal % sign. Just make them active and then expand them all to nothing. -\def\alias{\begingroup\obeyspaces\parsearg\aliasxxx} +\def\alias{\parseargusing\obeyspaces\aliasxxx} \def\aliasxxx #1{\aliasyyy#1\relax} -\def\aliasyyy #1=#2\relax{\ignoreactivespaces -\edef\next{\global\let\expandafter\noexpand\csname#1\endcsname=% - \expandafter\noexpand\csname#2\endcsname}% -\expandafter\endgroup\next} +\def\aliasyyy #1=#2\relax{% + {% + \expandafter\let\obeyedspace=\empty + \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}% + }% + \next +} \message{cross references,} -% @xref etc. \newwrite\auxfile @@ -5855,64 +5670,62 @@ width0pt\relax} \fi \def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, node \samp{\ignorespaces#1{}}} -% @node's job is to define \lastnode. -\def\node{\ENVcheck\parsearg\nodezzz} -\def\nodezzz#1{\nodexxx #1,\finishnodeparse} +% @node's only job in TeX is to define \lastnode, which is used in +% cross-references. +\parseargdef\node{\checkenv{}\nodexxx #1,\finishnodeparse} \def\nodexxx#1,#2\finishnodeparse{\gdef\lastnode{#1}} \let\nwnode=\node -\let\lastnode=\relax - -% The sectioning commands (@chapter, etc.) call these. -\def\donoderef{% - \ifx\lastnode\relax\else - \expandafter\expandafter\expandafter\setref{\lastnode}% - {Ysectionnumberandtype}% - \global\let\lastnode=\relax - \fi -} -\def\unnumbnoderef{% - \ifx\lastnode\relax\else - \expandafter\expandafter\expandafter\setref{\lastnode}{Ynothing}% - \global\let\lastnode=\relax +\let\lastnode=\empty + +% Write a cross-reference definition for the current node. #1 is the +% type (Ynumbered, Yappendix, Ynothing). +% +\def\donoderef#1{% + \ifx\lastnode\empty\else + \setref{\lastnode}{#1}% + \global\let\lastnode=\empty \fi } -\def\appendixnoderef{% - \ifx\lastnode\relax\else - \expandafter\expandafter\expandafter\setref{\lastnode}% - {Yappendixletterandtype}% - \global\let\lastnode=\relax - \fi -} - % @anchor{NAME} -- define xref target at arbitrary point. % \newcount\savesfregister -\gdef\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi} -\gdef\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi} -\gdef\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces} +% +\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi} +\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi} +\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces} % \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an -% anchor), namely NAME-title (the corresponding @chapter/etc. name), -% NAME-pg (the page number), and NAME-snt (section number and type). -% Called from \foonoderef. -% -% We have to set \indexdummies so commands such as @code in a section -% title aren't expanded. It would be nicer not to expand the titles in -% the first place, but there's so many layers that that is hard to do. -% -% Likewise, use \turnoffactive so that punctuation chars such as underscore +% anchor), which consists of three parts: +% 1) NAME-title - the current sectioning name, taken from \thissection; +% 2) NAME-snt - section number and type, defined as the SNT arg; +% 3) NAME-pg - the page number. +% This is called from \donoderef, \anchor, and \dofloat. +% +% We take care not to fully expand the title, since it may contain +% arbitrary macros. +% +% Use \turnoffactive so that punctuation chars such as underscore % and backslash work in node names. % -\def\setref#1#2{{% - \atdummies +\def\setref#1#2{% \pdfmkdest{#1}% - % - \turnoffactive - \dosetq{#1-title}{Ytitle}% - \dosetq{#1-pg}{Ypagenumber}% - \dosetq{#1-snt}{#2}% -}} + \iflinks + {% + \indexnofonts + \turnoffactive + \otherbackslash + \edef\writexrdef##1##2{% + \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef + ##1}{##2}}% these are parameters of \writexrdef + }% + \toks0 = \expandafter{\thissection}% + \immediate \writexrdef{title}{\the\toks0 }% + \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc. + \writexrdef{pg}{\folio}% will be written later, during \shipout + }% + \fi +} % @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is % the node name, #2 the name of the Info cross-reference, #3 the printed @@ -5925,38 +5738,33 @@ width0pt\relax} \fi \def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup \unsepspaces \def\printedmanual{\ignorespaces #5}% - \def\printednodename{\ignorespaces #3}% - \setbox1=\hbox{\printedmanual}% - \setbox0=\hbox{\printednodename}% + \def\printedrefname{\ignorespaces #3}% + \setbox1=\hbox{\printedmanual\unskip}% + \setbox0=\hbox{\printedrefname\unskip}% \ifdim \wd0 = 0pt % No printed node name was explicitly given. \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax % Use the node name inside the square brackets. - \def\printednodename{\ignorespaces #1}% + \def\printedrefname{\ignorespaces #1}% \else % Use the actual chapter/section title appear inside % the square brackets. Use the real section title if we have it. \ifdim \wd1 > 0pt % It is in another manual, so we don't have it. - \def\printednodename{\ignorespaces #1}% + \def\printedrefname{\ignorespaces #1}% \else \ifhavexrefs % We know the real title if we have the xref values. - \def\printednodename{\refx{#1-title}{}}% + \def\printedrefname{\refx{#1-title}{}}% \else % Otherwise just copy the Info node name. - \def\printednodename{\ignorespaces #1}% + \def\printedrefname{\ignorespaces #1}% \fi% \fi \fi \fi % - % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not - % insert empty discretionaries after hyphens, which means that it will - % not find a line break at a hyphen in a node names. Since some manuals - % are best written with fairly long node names, containing hyphens, this - % is a loss. Therefore, we give the text of the node name again, so it - % is as if TeX is seeing it for the first time. + % Make link in pdf output. \ifpdf \leavevmode \getfilename{#4}% @@ -5966,64 +5774,86 @@ width0pt\relax} \fi goto file{\the\filename.pdf} name{#1}% \else \startlink attr{/Border [0 0 0]}% - goto name{#1}% + goto name{\pdfmkpgn{#1}}% \fi }% \linkcolor \fi % - \ifdim \wd1 > 0pt - \putwordsection{} ``\printednodename'' \putwordin{} \cite{\printedmanual}% - \else - % _ (for example) has to be the character _ for the purposes of the - % control sequence corresponding to the node, but it has to expand - % into the usual \leavevmode...\vrule stuff for purposes of - % printing. So we \turnoffactive for the \refx-snt, back on for the - % printing, back off for the \refx-pg. - {\turnoffactive \otherbackslash - % Only output a following space if the -snt ref is nonempty; for - % @unnumbered and @anchor, it won't be. - \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% - \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi - }% - % output the `[mynode]' via a macro. - \xrefprintnodename\printednodename - % - % But we always want a comma and a space: - ,\space + % Float references are printed completely differently: "Figure 1.2" + % instead of "[somenode], p.3". We distinguish them by the + % LABEL-title being set to a magic string. + {% + % Have to otherify everything special to allow the \csname to + % include an _ in the xref name, etc. + \indexnofonts + \turnoffactive + \otherbackslash + \expandafter\global\expandafter\let\expandafter\Xthisreftitle + \csname X#1-title\endcsname + }% + \ifx \Xthisreftitle \floatmagic + % If the user specified the print name (third arg) to the ref, + % print it instead of our usual "Figure 1.2". + \ifdim\wd0 = 0pt + \refx{#1-snt}% + \else + \printedrefname + \fi % - % output the `page 3'. - \turnoffactive \otherbackslash \putwordpage\tie\refx{#1-pg}{}% + % if the user also gave the printed manual name (fifth arg), append + % "in MANUALNAME". + \ifdim \wd1 > 0pt + \space \putwordin{} \cite{\printedmanual}% + \fi + \else + % node/anchor (non-float) references. + % + % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not + % insert empty discretionaries after hyphens, which means that it will + % not find a line break at a hyphen in a node names. Since some manuals + % are best written with fairly long node names, containing hyphens, this + % is a loss. Therefore, we give the text of the node name again, so it + % is as if TeX is seeing it for the first time. + \ifdim \wd1 > 0pt + \putwordsection{} ``\printedrefname'' \putwordin{} \cite{\printedmanual}% + \else + % _ (for example) has to be the character _ for the purposes of the + % control sequence corresponding to the node, but it has to expand + % into the usual \leavevmode...\vrule stuff for purposes of + % printing. So we \turnoffactive for the \refx-snt, back on for the + % printing, back off for the \refx-pg. + {\turnoffactive \otherbackslash + % Only output a following space if the -snt ref is nonempty; for + % @unnumbered and @anchor, it won't be. + \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% + \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi + }% + % output the `[mynode]' via a macro so it can be overridden. + \xrefprintnodename\printedrefname + % + % But we always want a comma and a space: + ,\space + % + % output the `page 3'. + \turnoffactive \otherbackslash \putwordpage\tie\refx{#1-pg}{}% + \fi \fi \endlink \endgroup} % This macro is called from \xrefX for the `[nodename]' part of xref % output. It's a separate macro only so it can be changed more easily, -% since not square brackets don't work in some documents. Particularly +% since square brackets don't work well in some documents. Particularly % one that Bob is working on :). % \def\xrefprintnodename#1{[#1]} -% \dosetq is called from \setref to do the actual \write (\iflinks). +% Things referred to by \setref. % -\def\dosetq#1#2{% - {\let\folio=0% - \edef\next{\write\auxfile{\internalsetq{#1}{#2}}}% - \iflinks \next \fi - }% -} - -% \internalsetq{foo}{page} expands into -% CHARACTERS @xrdef{foo}{...expansion of \page...} -\def\internalsetq#1#2{@xrdef{#1}{\csname #2\endcsname}} - -% Things to be expanded by \internalsetq. -% -\def\Ypagenumber{\folio} -\def\Ytitle{\thissection} \def\Ynothing{} -\def\Ysectionnumberandtype{% +\def\Yomitfromtoc{} +\def\Ynumbered{% \ifnum\secno=0 \putwordChapter@tie \the\chapno \else \ifnum\subsecno=0 @@ -6034,8 +5864,7 @@ width0pt\relax} \fi \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno \fi\fi\fi } - -\def\Yappendixletterandtype{% +\def\Yappendix{% \ifnum\secno=0 \putwordAppendix@tie @char\the\appendixno{}% \else \ifnum\subsecno=0 @@ -6048,15 +5877,6 @@ width0pt\relax} \fi \fi\fi\fi } -% Use TeX 3.0's \inputlineno to get the line number, for better error -% messages, but if we're using an old version of TeX, don't do anything. -% -\ifx\inputlineno\thisisundefined - \let\linenumber = \empty % Pre-3.0. -\else - \def\linenumber{\the\inputlineno:\space} -\fi - % Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. % If its value is nonempty, SUFFIX is output afterward. % @@ -6092,6 +5912,16 @@ width0pt\relax} \fi \def\xrdef#1{\expandafter\gdef\csname X#1\endcsname} % Read the last existing aux file, if any. No error if none exists. +% +\def\tryauxfile{% + \openin 1 \jobname.aux + \ifeof 1 \else + \readauxfile + \global\havexrefstrue + \fi + \closein 1 +} + \def\readauxfile{\begingroup \catcode`\^^@=\other \catcode`\^^A=\other @@ -6160,31 +5990,17 @@ width0pt\relax} \fi }% }% % - % Turn off \ as an escape so we do not lose on - % entries which were dumped with control sequences in their names. - % For example, @xrdef{$\leq $-fun}{page ...} made by @defun ^^ - % Reference to such entries still does not work the way one would wish, - % but at least they do not bomb out when the aux file is read in. - \catcode`\\=\other - % % @ is our escape character in .aux files. \catcode`\{=1 \catcode`\}=2 \catcode`\@=0 % - \openin 1 \jobname.aux - \ifeof 1 \else - \closein 1 - \input \jobname.aux - \global\havexrefstrue - \global\warnedobstrue - \fi - % Open the new aux file. TeX will close it automatically at exit. - \openout\auxfile=\jobname.aux + \input \jobname.aux \endgroup} -% Footnotes. +\message{insertions,} +% including footnotes. \newcount \footnoteno @@ -6198,13 +6014,12 @@ width0pt\relax} \fi % @footnotestyle is meaningful for info output only. \let\footnotestyle=\comment -\let\ptexfootnote=\footnote - {\catcode `\@=11 % % Auto-number footnotes. Otherwise like plain. \gdef\footnote{% \let\indent=\ptexindent + \let\noindent=\ptexnoindent \global\advance\footnoteno by \@ne \edef\thisfootno{$^{\the\footnoteno}$}% % @@ -6222,17 +6037,12 @@ width0pt\relax} \fi % Don't bother with the trickery in plain.tex to not require the % footnote text as a parameter. Our footnotes don't need to be so general. % -% Oh yes, they do; otherwise, @ifset and anything else that uses -% \parseargline fail inside footnotes because the tokens are fixed when +% Oh yes, they do; otherwise, @ifset (and anything else that uses +% \parseargline) fails inside footnotes because the tokens are fixed when % the footnote is read. --karl, 16nov96. % -% The start of the footnote looks usually like this: -\gdef\startfootins{\insert\footins\bgroup} -% -% ... but this macro is redefined inside @multitable. -% \gdef\dofootnote{% - \startfootins + \insert\footins\bgroup % We want to typeset this text as a normal paragraph, even if the % footnote reference occurs in (for example) a display environment. % So reset some parameters. @@ -6268,40 +6078,66 @@ width0pt\relax} \fi } }%end \catcode `\@=11 -% @| inserts a changebar to the left of the current line. It should -% surround any changed text. This approach does *not* work if the -% change spans more than two lines of output. To handle that, we would -% have adopt a much more difficult approach (putting marks into the main -% vertical list for the beginning and end of each change). +% In case a @footnote appears in a vbox, save the footnote text and create +% the real \insert just after the vbox finished. Otherwise, the insertion +% would be lost. +% Similarily, if a @footnote appears inside an alignment, save the footnote +% text to a box and make the \insert when a row of the table is finished. +% And the same can be done for other insert classes. --kasal, 16nov03. + +% Replace the \insert primitive by a cheating macro. +% Deeper inside, just make sure that the saved insertions are not spilled +% out prematurely. % -\def\|{% - % \vadjust can only be used in horizontal mode. - \leavevmode - % - % Append this vertical mode material after the current line in the output. - \vadjust{% - % We want to insert a rule with the height and depth of the current - % leading; that is exactly what \strutbox is supposed to record. - \vskip-\baselineskip - % - % \vadjust-items are inserted at the left edge of the type. So - % the \llap here moves out into the left-hand margin. - \llap{% - % - % For a thicker or thinner bar, change the `1pt'. - \vrule height\baselineskip width1pt - % - % This is the space between the bar and the text. - \hskip 12pt - }% - }% +\def\startsavinginserts{% + \ifx \insert\ptexinsert + \let\insert\saveinsert + \else + \let\checkinserts\relax + \fi } -% For a final copy, take out the rectangles -% that mark overfull boxes (in case you have decided -% that the text looks ok even though it passes the margin). +% This \insert replacements works for both \insert\footins{xx} and +% \insert\footins\bgroup xx\egroup, but it doesn't work for \insert27{xx}. % -\def\finalout{\overfullrule=0pt} +\def\saveinsert#1{% + \edef\next{\noexpand\savetobox \makeSAVEname#1}% + \afterassignment\next + % swallow the left brace + \let\temp = +} +\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}} +\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1} + +\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi} + +\def\placesaveins#1{% + \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname + {\box#1}% +} + +% eat @SAVE -- beware, all of them have catcode \other: +{ + \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials % ;-) + \gdef\gobblesave @SAVE{} +} + +% initialization: +\def\newsaveins #1{% + \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}% + \next +} +\def\newsaveinsX #1{% + \csname newbox\endcsname #1% + \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts + \checksaveins #1}% +} + +% initialize: +\let\checkinserts\empty +\newsaveins\footins +\newsaveins\margin + % @image. We use the macros from epsf.tex to support this. % If epsf.tex is not installed and @image is used, we complain. @@ -6311,12 +6147,12 @@ width0pt\relax} \fi % undone and the next image would fail. \openin 1 = epsf.tex \ifeof 1 \else - \closein 1 % Do not bother showing banner with epsf.tex v2.7k (available in % doc/epsf.tex and on ctan). \def\epsfannounce{\toks0 = }% \input epsf.tex \fi +\closein 1 % % We will only complain once about lack of epsf.tex. \newif\ifwarnednoepsf @@ -6372,6 +6208,129 @@ width0pt\relax} \fi \endgroup} +% @float FLOATTYPE,LOC ... @end float for displayed figures, tables, etc. +% We don't actually implement floating yet, we just plop the float "here". +% But it seemed the best name for the future. +% +\envparseargdef\float{\dofloat #1,,,\finish} + +% #1 is the optional FLOATTYPE, the text label for this float, typically +% "Figure", "Table", "Example", etc. Can't contain commas. If omitted, +% this float will not be numbered and cannot be referred to. +% +% #2 is the optional xref label. Also must be present for the float to +% be referable. +% +% #3 is the optional positioning argument; for now, it is ignored. It +% will somehow specify the positions allowed to float to (here, top, bottom). +% +% We keep a separate counter for each FLOATTYPE, which we reset at each +% chapter-level command. +\let\resetallfloatnos=\empty +% +\def\dofloat#1,#2,#3,#4\finish{% + % don't lose footnotes inside @float. + \startsavinginserts + % + \vtop\bgroup + \def\floattype{#1}% + \def\floatlabel{#2}% + \def\floatloc{#3}% we do nothing with this yet. + % xx should we indent the whole thing? center it? + % + \ifx\floattype\empty \else + % For now, assume the FLOATTYPE is entirely letters, so we just use it + % in a control sequence name literally. We want each FLOATTYPE to be + % numbered separately (Figure 1, Table 1, Figure 2, ...). + \expandafter\getfloatno\csname\floattype floatno\endcsname + \global\advance\floatno by 1 + % + \ifx\floatlabel\empty \else + {% + % This magic value for \thissection is output by \setref as the + % XREFLABEL-title value. \xrefX uses it to distinguish float + % labels (which have a completely different output format) from + % nodes and xref labels. + % + \let\thissection=\floatmagic + \setref{\floatlabel}{Yfloat}% + }% + \fi + \fi +} + +% we have four possibilities: +% @float Foo & @caption{Cap}: Foo 1.1: Cap +% @float Foo & no caption: Foo 1.1 +% @float & @caption{Cap}: Cap +% @float & no caption: +% +\def\Efloat{% + \let\printedsomething = \empty + % + \ifx\floattype\empty \else + \vskip.5\parskip % space above caption + % + % Print the float number preceded by the chapter-level number + % (empty in the case of unnumbered). Although there are other + % styles of float numbering, we hardwire this one. + \floattype\space\chaplevelprefix\the\floatno + \let\printedsomething = t% + \fi + % + \ifx\thiscaption\empty \else + \ifx\printedsomething\empty + \vskip.5\parskip % space above caption + \else + :\space % had a number, so print a colon. + \fi + % + % Print caption text. + \thiscaption + \let\printedsomething = t% + \fi + % + % Space below caption, if we printed anything. + \ifx\printedsomething\empty \else \vskip\parskip \fi + % + \egroup % end of \vtop + \checkinserts +} + +\def\caption#1{\checkenv\float \def\thiscaption{#1}} +\def\shortcaption#1{\checkenv\float \def\thisshortcaption{#1}} +\let\thiscaption=\empty +\let\thisshortcaption=\empty + +% The parameter is the control sequence identifying the counter we are +% going to use. Create it if it doesn't exist and assign it to \floatno. +\def\getfloatno#1{% + \ifx#1\relax + % Haven't seen this figure type before. + \csname newcount\endcsname #1% + % + % Remember to reset this floatno at the next chap. + \expandafter\gdef\expandafter\resetallfloatnos + \expandafter{\resetallfloatnos #1=0 }% + \fi + \let\floatno#1% +} + +% \setref calls this to get the XREFLABEL-snt value. We want an @xref +% to the FLOATLABEL to expand to "Figure 3.1". We call \setref when we +% first read the @float command. +% +\def\Yfloat{\floattype @tie{}\chaplevelprefix\the\floatno}% + +% Magic string used for the XREFLABEL-title value, so \xrefX can +% distinguish floats from other xref types. +\def\floatmagic{!!float!!} + +% @listoffloats FLOATTYPE - print a list of floats like a table of contents. +\parseargdef\listoffloats{%xx +} + + \message{localization,} % and i18n. @@ -6380,19 +6339,17 @@ width0pt\relax} \fi % properly. Single argument is the language abbreviation. % It would be nice if we could set up a hyphenation file here. % -\def\documentlanguage{\parsearg\dodocumentlanguage} -\def\dodocumentlanguage#1{% +\parseargdef\documentlanguage{% \tex % read txi-??.tex file in plain TeX. - % Read the file if it exists. - \openin 1 txi-#1.tex - \ifeof1 - \errhelp = \nolanghelp - \errmessage{Cannot read language file txi-#1.tex}% - \let\temp = \relax - \else - \def\temp{\input txi-#1.tex }% - \fi - \temp + % Read the file if it exists. + \openin 1 txi-#1.tex + \ifeof 1 + \errhelp = \nolanghelp + \errmessage{Cannot read language file txi-#1.tex}% + \else + \input txi-#1.tex + \fi + \closein 1 \endgroup } \newhelp\nolanghelp{The given language definition file cannot be found or @@ -6575,8 +6532,7 @@ should work if nowhere else does.} % Perhaps we should allow setting the margins, \topskip, \parskip, % and/or leading, also. Or perhaps we should compute them somehow. % -\def\pagesizes{\parsearg\pagesizesxxx} -\def\pagesizesxxx#1{\pagesizesyyy #1,,\finish} +\parseargdef\pagesizes{\pagesizesyyy #1,,\finish} \def\pagesizesyyy#1,#2,#3\finish{{% \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi \globaldefs = 1 @@ -6623,8 +6579,8 @@ should work if nowhere else does.} \def\normalplus{+} \def\normaldollar{$}%$ font-lock fix -% This macro is used to make a character print one way in ttfont -% where it can probably just be output, and another way in other fonts, +% This macro is used to make a character print one way in \tt +% (where it can probably be output as-is), and another way in other fonts, % where something hairier probably needs to be done. % % #1 is what to print if we are indeed using \tt; #2 is what to print @@ -6672,13 +6628,6 @@ should work if nowhere else does.} \catcode`\$=\active \def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix -% Set up an active definition for =, but don't enable it most of the time. -{\catcode`\==\active -\global\def={{\tt \char 61}}} - -\catcode`+=\active -\catcode`\_=\active - % If a .fmt file is being used, characters that might appear in a file % name cannot be active until we have parsed the command line. % So turn them off again, and have \everyjob (or @setfilename) turn them on. @@ -6720,6 +6669,7 @@ should work if nowhere else does.} @let>=@normalgreater @let+=@normalplus @let$=@normaldollar %$ font-lock fix + @unsepspaces } % Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of @@ -6759,10 +6709,6 @@ should work if nowhere else does.} @catcode`@# = @other @catcode`@% = @other -@c Set initial fonts. -@textfonts -@rm - @c Local variables: @c eval: (add-hook 'write-file-hooks 'time-stamp) @@ -6771,3 +6717,9 @@ should work if nowhere else does.} @c time-stamp-format: "%:y-%02m-%02d.%02H" @c time-stamp-end: "}" @c End: + +@c vim:sw=2: + +@ignore + arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115 +@end ignore diff --git a/contrib/gcc/doc/interface.texi b/contrib/gcc/doc/interface.texi index c554434..b55293d 100644 --- a/contrib/gcc/doc/interface.texi +++ b/contrib/gcc/doc/interface.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001 Free Software Foundation, Inc. +@c 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -28,8 +28,8 @@ 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 machine-description macros @code{STRUCT_VALUE} and -@code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address. +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 @@ -76,27 +76,10 @@ just take the address of the variable. If a variable's address is ever taken, even if just to compute it and ignore it, then the variable cannot go in a register: -@example +@smallexample @{ int careful; &careful; @dots{} @} -@end example - -@cindex arithmetic libraries -@cindex math libraries -@opindex msoft-float -Code compiled with GCC may call certain library routines. Most of -them handle arithmetic for which there are no instructions. This -includes multiply and divide on some machines, and floating point -operations on any machine for which floating point support is disabled -with @option{-msoft-float}. Some standard parts of the C library, such as -@code{bcopy} or @code{memcpy}, are also called automatically. The usual -function call interface is used for calling the library routines. - -Some of these routines can be defined in mostly machine-independent C; -they appear in @file{libgcc2.c}. Others must be hand-written in -assembly language for each processor. Wherever they are defined, they -are compiled into the support library, @file{libgcc.a}, which is -automatically searched when you link programs with GCC@. +@end smallexample diff --git a/contrib/gcc/doc/invoke.texi b/contrib/gcc/doc/invoke.texi index 6a12890..7e88bd5 100644 --- a/contrib/gcc/doc/invoke.texi +++ b/contrib/gcc/doc/invoke.texi @@ -1,12 +1,12 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, -@c 2000, 2001, 2002, 2003 Free Software Foundation, Inc. +@c 2000, 2001, 2002, 2003, 2004 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{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, -1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. +1998, 1999, 2000, 2001, 2002, 2003, 2004 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 @@ -140,6 +140,7 @@ only one of these two forms, whichever one is not the default. * Code Gen Options:: Specifying conventions for function calls, data layout and register usage. * Environment Variables:: Env vars that affect GCC. +* Precompiled Headers:: Compiling a header once, and using it many times. * Running Protoize:: Automatically adding or removing function prototypes. @end menu @@ -171,10 +172,9 @@ in the following sections. @item C++ Language Options @xref{C++ Dialect Options,,Options Controlling C++ Dialect}. @gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol --fconserve-space -fno-const-strings -fdollars-in-identifiers @gol +-fconserve-space -fno-const-strings @gol -fno-elide-constructors @gol --fno-enforce-eh-specs -fexternal-templates @gol --falt-external-templates @gol +-fno-enforce-eh-specs @gol -ffor-scope -fno-for-scope -fno-gnu-keywords @gol -fno-implicit-templates @gol -fno-implicit-inline-templates @gol @@ -182,7 +182,7 @@ in the following sections. -fno-nonansi-builtins -fno-operator-names @gol -fno-optional-diags -fpermissive @gol -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol --fuse-cxa-atexit -fvtable-gc -fno-weak -nostdinc++ @gol +-fuse-cxa-atexit -fno-weak -nostdinc++ @gol -fno-default-inline -Wabi -Wctor-dtor-privacy @gol -Wnon-virtual-dtor -Wreorder @gol -Weffc++ -Wno-deprecated @gol @@ -192,33 +192,39 @@ in the following sections. @item Objective-C Language Options @xref{Objective-C Dialect Options,,Options Controlling Objective-C Dialect}. -@gccoptlist{-fconstant-string-class=@var{class-name} @gol --fgnu-runtime -fnext-runtime -gen-decls @gol --Wno-protocol -Wselector -Wundeclared-selector} +@gccoptlist{ +-fconstant-string-class=@var{class-name} @gol +-fgnu-runtime -fnext-runtime @gol +-fno-nil-receivers @gol +-fobjc-exceptions @gol +-freplace-objc-classes @gol +-fzero-link @gol +-gen-decls @gol +-Wno-protocol -Wselector -Wundeclared-selector} @item Language Independent Options @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}. -@gccoptlist{-fmessage-length=@var{n} @gol +@gccoptlist{-fmessage-length=@var{n} @gol -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}} @item Warning Options @xref{Warning Options,,Options to Request or Suppress Warnings}. @gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol --w -W -Wall -Waggregate-return @gol +-w -Wextra -Wall -Waggregate-return @gol -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol -Wconversion -Wno-deprecated-declarations @gol --Wdisabled-optimization -Wno-div-by-zero -Werror @gol +-Wdisabled-optimization -Wno-div-by-zero -Wendif-labels @gol +-Werror -Werror-implicit-function-declaration @gol -Wfloat-equal -Wformat -Wformat=2 @gol --Wformat-nonliteral -Wformat-security @gol --Wimplicit -Wimplicit-int @gol --Wimplicit-function-declaration @gol --Werror-implicit-function-declaration @gol --Wimport -Winline -Wno-endif-labels @gol +-Wno-format-extra-args -Wformat-nonliteral @gol +-Wformat-security -Wformat-y2k @gol +-Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol +-Wimport -Wno-import -Winit-self -Winline @gol +-Wno-invalid-offsetof -Winvalid-pch @gol -Wlarger-than-@var{len} -Wlong-long @gol -Wmain -Wmissing-braces @gol -Wmissing-format-attribute -Wmissing-noreturn @gol --Wno-multichar -Wno-format-extra-args -Wno-format-y2k @gol --Wno-import -Wnonnull -Wpacked -Wpadded @gol +-Wno-multichar -Wnonnull -Wpacked -Wpadded @gol -Wparentheses -Wpointer-arith -Wredundant-decls @gol -Wreturn-type -Wsequence-point -Wshadow @gol -Wsign-compare -Wstrict-aliasing @gol @@ -230,8 +236,9 @@ in the following sections. @item C-only Warning Options @gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol --Wmissing-prototypes -Wnested-externs @gol --Wstrict-prototypes -Wtraditional} +-Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol +-Wstrict-prototypes -Wtraditional @gol +-Wdeclaration-after-statement} @item Debugging Options @xref{Debugging Options,,Options for Debugging Your Program or GCC}. @@ -241,10 +248,11 @@ in the following sections. -fdump-tree-original@r{[}-@var{n}@r{]} @gol -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol --feliminate-dwarf2-dups -fmem-report @gol --fprofile-arcs -frandom-seed=@var{n} @gol --fsched-verbose=@var{n} -ftest-coverage -ftime-report @gol --g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2 @gol +-feliminate-dwarf2-dups -feliminate-unused-debug-types @gol +-feliminate-unused-debug-symbols -fmem-report -fprofile-arcs @gol +-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol +-ftest-coverage -ftime-report @gol +-g -g@var{level} -gcoff -gdwarf-2 @gol -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol -print-multi-directory -print-multi-lib @gol @@ -255,13 +263,14 @@ in the following sections. @xref{Optimize Options,,Options that Control Optimization}. @gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol -falign-labels=@var{n} -falign-loops=@var{n} @gol --fbranch-probabilities -fcaller-saves -fcprop-registers @gol +-fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol +-fbranch-target-load-optimize2 -fcaller-saves -fcprop-registers @gol -fcse-follow-jumps -fcse-skip-blocks -fdata-sections @gol -fdelayed-branch -fdelete-null-pointer-checks @gol -fexpensive-optimizations -ffast-math -ffloat-store @gol -fforce-addr -fforce-mem -ffunction-sections @gol --fgcse -fgcse-lm -fgcse-sm -floop-optimize -fcrossjumping @gol --fif-conversion -fif-conversion2 @gol +-fgcse -fgcse-lm -fgcse-sm -fgcse-las -floop-optimize @gol +-fcrossjumping -fif-conversion -fif-conversion2 @gol -finline-functions -finline-limit=@var{n} -fkeep-inline-functions @gol -fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol -fmove-all-movables -fnew-ra -fno-branch-count-reg @gol @@ -272,21 +281,26 @@ in the following sections. -fno-trapping-math -fno-zero-initialized-in-bss @gol -fomit-frame-pointer -foptimize-register-move @gol -foptimize-sibling-calls -fprefetch-loop-arrays @gol +-fprofile-generate -fprofile-use @gol -freduce-all-givs -fregmove -frename-registers @gol -freorder-blocks -freorder-functions @gol -frerun-cse-after-loop -frerun-loop-opt @gol --fschedule-insns -fschedule-insns2 @gol +-frounding-math -fschedule-insns -fschedule-insns2 @gol -fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol --fsched-spec-load-dangerous -fsignaling-nans @gol --fsingle-precision-constant -fssa -fssa-ccp -fssa-dce @gol +-fsched-spec-load-dangerous @gol +-fsched-stalled-insns=@var{n} -sched-stalled-insns-dep=@var{n} @gol +-fsched2-use-superblocks @gol +-fsched2-use-traces -fsignaling-nans @gol +-fsingle-precision-constant @gol -fstrength-reduce -fstrict-aliasing -ftracer -fthread-jumps @gol --funroll-all-loops -funroll-loops @gol ---param @var{name}=@var{value} @gol +-funroll-all-loops -funroll-loops -fpeel-loops @gol +-funswitch-loops -fold-unroll-loops -fold-unroll-all-loops @gol +--param @var{name}=@var{value} -O -O0 -O1 -O2 -O3 -Os} @item Preprocessor Options @xref{Preprocessor Options,,Options Controlling the Preprocessor}. -@gccoptlist{-$ -A@var{question}=@var{answer} @gol +@gccoptlist{-A@var{question}=@var{answer} @gol -A-@var{question}@r{[}=@var{answer}@r{]} @gol -C -dD -dI -dM -dN @gol -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol @@ -294,17 +308,19 @@ in the following sections. -include @var{file} -imacros @var{file} @gol -iprefix @var{file} -iwithprefix @var{dir} @gol -iwithprefixbefore @var{dir} -isystem @var{dir} @gol --M -MM -MF -MG -MP -MQ -MT -nostdinc -P -remap @gol --trigraphs -undef -U@var{macro} -Wp,@var{option}} +-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol +-P -fworking-directory -remap @gol +-trigraphs -undef -U@var{macro} -Wp,@var{option} @gol +-Xpreprocessor @var{option}} @item Assembler Option @xref{Assembler Options,,Passing Options to the Assembler}. -@gccoptlist{-Wa,@var{option}} +@gccoptlist{-Wa,@var{option} -Xassembler @var{option}} @item Linker Options @xref{Link Options,,Options for Linking}. @gccoptlist{@var{object-file-name} -l@var{library} @gol --nostartfiles -nodefaultlibs -nostdlib @gol +-nostartfiles -nodefaultlibs -nostdlib -pie @gol -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol -Wl,@var{option} -Xlinker @var{option} @gol -u @var{symbol}} @@ -324,11 +340,12 @@ in the following sections. @emph{M680x0 Options} @gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol -m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020 @gol --mfpa -mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol --malign-int -mstrict-align} +-mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol +-malign-int -mstrict-align -msep-data -mno-sep-data @gol +-mshared-library-id=n -mid-shared-library -mno-id-shared-library} @emph{M68hc1x Options} -@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol +@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol -mauto-incdec -minmax -mlong-calls -mshort @gol -msoft-reg-count=@var{count}} @@ -339,15 +356,18 @@ in the following sections. @gccoptlist{-mcpu=@var{cpu-type} @gol -mtune=@var{cpu-type} @gol -mcmodel=@var{code-model} @gol --m32 -m64 @gol --mapp-regs -mbroken-saverestore -mcypress @gol --mfaster-structs -mflat @gol --mfpu -mhard-float -mhard-quad-float @gol --mimpure-text -mlittle-endian -mlive-g0 -mno-app-regs @gol --mno-faster-structs -mno-flat -mno-fpu @gol --mno-impure-text -mno-stack-bias -mno-unaligned-doubles @gol --msoft-float -msoft-quad-float -msparclite -mstack-bias @gol --msupersparc -munaligned-doubles -mv8} +-m32 -m64 -mapp-regs -mno-app-regs @gol +-mfaster-structs -mno-faster-structs @gol +-mflat -mno-flat -mfpu -mno-fpu @gol +-mhard-float -msoft-float @gol +-mhard-quad-float -msoft-quad-float @gol +-mimpure-text -mno-impure-text -mlittle-endian @gol +-mstack-bias -mno-stack-bias @gol +-munaligned-doubles -mno-unaligned-doubles @gol +-mv8plus -mno-v8plus -mvis -mno-vis @gol +-mcypress -mf930 -mf934 @gol +-msparclite -msupersparc -mv8 +-threads -pthreads} @emph{ARM Options} @gccoptlist{-mapcs-frame -mno-apcs-frame @gol @@ -367,34 +387,29 @@ in the following sections. -msingle-pic-base -mno-single-pic-base @gol -mpic-register=@var{reg} @gol -mnop-fun-dllimport @gol +-mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol -mpoke-function-name @gol -mthumb -marm @gol -mtpcs-frame -mtpcs-leaf-frame @gol -mcaller-super-interworking -mcallee-super-interworking} -@emph{MN10200 Options} -@gccoptlist{-mrelax} - @emph{MN10300 Options} @gccoptlist{-mmult-bug -mno-mult-bug @gol -mam33 -mno-am33 @gol +-mam33-2 -mno-am33-2 @gol -mno-crt0 -mrelax} @emph{M32R/D Options} -@gccoptlist{-m32rx -m32r -mcode-model=@var{model-type} @gol --msdata=@var{sdata-type} -G @var{num}} - -@emph{M88K Options} -@gccoptlist{-m88000 -m88100 -m88110 -mbig-pic @gol --mcheck-zero-division -mhandle-large-shift @gol --midentify-revision -mno-check-zero-division @gol --mno-ocs-debug-info -mno-ocs-frame-position @gol --mno-optimize-arg-area -mno-serialize-volatile @gol --mno-underscores -mocs-debug-info @gol --mocs-frame-position -moptimize-arg-area @gol --mserialize-volatile -mshort-data-@var{num} -msvr3 @gol --msvr4 -mtrap-large-shift -muse-div-instruction @gol --mversion-03.00 -mwarn-passed-structs} +@gccoptlist{-m32r2 -m32rx -m32r @gol +-mdebug @gol +-malign-loops -mno-align-loops @gol +-missue-rate=@var{number} @gol +-mbranch-cost=@var{number} @gol +-mmodel=@var{code-size-model-type} @gol +-msdata=@var{sdata-type} @gol +-mno-flush-func -mflush-func=@var{name} @gol +-mno-flush-trap -mflush-trap=@var{number} @gol +-G @var{num}} @emph{RS/6000 and PowerPC Options} @gccoptlist{-mcpu=@var{cpu-type} @gol @@ -407,85 +422,88 @@ in the following sections. -mnew-mnemonics -mold-mnemonics @gol -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol -m64 -m32 -mxl-call -mno-xl-call -mpe @gol +-malign-power -malign-natural @gol -msoft-float -mhard-float -mmultiple -mno-multiple @gol -mstring -mno-string -mupdate -mno-update @gol -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol -mstrict-align -mno-strict-align -mrelocatable @gol -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 +-mdynamic-no-pic @gol +-mprioritize-restricted-insns=@var{priority} @gol +-msched-costly-dep=@var{dependence_type} @gol +-minsert-sched-nops=@var{scheme} @gol +-mcall-sysv -mcall-netbsd @gol -maix-struct-return -msvr4-struct-return @gol -mabi=altivec -mabi=no-altivec @gol -mabi=spe -mabi=no-spe @gol -misel=yes -misel=no @gol +-mspe=yes -mspe=no @gol +-mfloat-gprs=yes -mfloat-gprs=no @gol -mprototype -mno-prototype @gol -msim -mmvme -mads -myellowknife -memb -msdata @gol -msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread} @emph{Darwin Options} -@gccoptlist{ --all_load -allowable_client -arch -arch_errors_fatal @gol --arch_only -bind_at_load -bundle -bundle_loader @gol --client_name -compatibility_version -current_version @gol --dependency-file -dylib_file -dylinker_install_name @gol --dynamic -dynamiclib -exported_symbols_list @gol --filelist -flat_namespace -force_cpusubtype_ALL @gol --force_flat_namespace -headerpad_max_install_names @gol --image_base -init -install_name -keep_private_externs @gol --multi_module -multiply_defined -multiply_defined_unused @gol --noall_load -nomultidefs -noprebind -noseglinkedit @gol --pagezero_size -prebind -prebind_all_twolevel_modules @gol --private_bundle -read_only_relocs -sectalign @gol --sectobjectsymbols -whyload -seg1addr @gol --sectcreate -sectobjectsymbols -sectorder @gol --seg_addr_table -seg_addr_table_filename -seglinkedit @gol --segprot -segs_read_only_addr -segs_read_write_addr @gol --single_module -static -sub_library -sub_umbrella @gol --twolevel_namespace -umbrella -undefined @gol --unexported_symbols_list -weak_reference_mismatches -whatsloaded} - -@emph{RT Options} -@gccoptlist{-mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs @gol --mfull-fp-blocks -mhc-struct-return -min-line-mul @gol --mminimum-fp-blocks -mnohc-struct-return} +@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol +-arch_only -bind_at_load -bundle -bundle_loader @gol +-client_name -compatibility_version -current_version @gol +-dependency-file -dylib_file -dylinker_install_name @gol +-dynamic -dynamiclib -exported_symbols_list @gol +-filelist -flat_namespace -force_cpusubtype_ALL @gol +-force_flat_namespace -headerpad_max_install_names @gol +-image_base -init -install_name -keep_private_externs @gol +-multi_module -multiply_defined -multiply_defined_unused @gol +-noall_load -nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol +-pagezero_size -prebind -prebind_all_twolevel_modules @gol +-private_bundle -read_only_relocs -sectalign @gol +-sectobjectsymbols -whyload -seg1addr @gol +-sectcreate -sectobjectsymbols -sectorder @gol +-seg_addr_table -seg_addr_table_filename -seglinkedit @gol +-segprot -segs_read_only_addr -segs_read_write_addr @gol +-single_module -static -sub_library -sub_umbrella @gol +-twolevel_namespace -umbrella -undefined @gol +-unexported_symbols_list -weak_reference_mismatches @gol +-whatsloaded} @emph{MIPS Options} -@gccoptlist{-mabicalls -march=@var{cpu-type} -mtune=@var{cpu=type} @gol --mcpu=@var{cpu-type} -membedded-data -muninit-const-in-rodata @gol --membedded-pic -mfp32 -mfp64 -mfused-madd -mno-fused-madd @gol --mgas -mgp32 -mgp64 @gol --mgpopt -mhalf-pic -mhard-float -mint64 -mips1 @gol --mips2 -mips3 -mips4 -mlong64 -mlong32 -mlong-calls -mmemcpy @gol --mmips-as -mmips-tfile -mno-abicalls @gol --mno-embedded-data -mno-uninit-const-in-rodata @gol --mno-embedded-pic -mno-gpopt -mno-long-calls @gol --mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats @gol --mrnames -msoft-float @gol --m4650 -msingle-float -mmad @gol --mstats -EL -EB -G @var{num} -nocpp @gol --mabi=32 -mabi=n32 -mabi=64 -mabi=eabi @gol --mfix7000 -mno-crt0 -mflush-func=@var{func} -mno-flush-func @gol --mbranch-likely -mno-branch-likely} +@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol +-mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol +-mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol +-mxgot -mno-xgot -membedded-pic -mno-embedded-pic @gol +-mgp32 -mgp64 -mfp32 -mfp64 -mhard-float -msoft-float @gol +-msingle-float -mdouble-float -mint64 -mlong64 -mlong32 @gol +-G@var{num} -membedded-data -mno-embedded-data @gol +-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol +-msplit-addresses -mno-split-addresses @gol +-mexplicit-relocs -mno-explicit-relocs @gol +-mrnames -mno-rnames @gol +-mcheck-zero-division -mno-check-zero-division @gol +-mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol +-mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol +-mfix-sb1 -mno-fix-sb1 -mflush-func=@var{func} @gol +-mno-flush-func -mbranch-likely -mno-branch-likely} @emph{i386 and x86-64 Options} -@gccoptlist{-mcpu=@var{cpu-type} -march=@var{cpu-type} @gol --mfpmath=@var{unit} -masm=@var{dialect} -mno-fancy-math-387 @gol +@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol +-mfpmath=@var{unit} @gol +-masm=@var{dialect} -mno-fancy-math-387 @gol -mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol -mno-wide-multiply -mrtd -malign-double @gol -mpreferred-stack-boundary=@var{num} @gol --mmmx -msse -msse2 -mpni -m3dnow @gol +-mmmx -msse -msse2 -msse3 -m3dnow @gol -mthreads -mno-align-stringops -minline-all-stringops @gol -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol -m96bit-long-double -mregparm=@var{num} -momit-leaf-frame-pointer @gol --mno-red-zone@gol +-mno-red-zone -mno-tls-direct-seg-refs @gol -mcmodel=@var{code-model} @gol -m32 -m64} @emph{HPPA Options} @gccoptlist{-march=@var{architecture-type} @gol -mbig-switch -mdisable-fpregs -mdisable-indexing @gol --mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol --mjump-in-delay -mlinker-opt -mlong-calls @gol +-mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol +-mjump-in-delay -mlinker-opt -mlong-calls @gol -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol -mno-jump-in-delay -mno-long-load-store @gol @@ -514,6 +532,7 @@ in the following sections. -mbwx -mmax -mfix -mcix @gol -mfloat-vax -mfloat-ieee @gol -mexplicit-relocs -msmall-data -mlarge-data @gol +-msmall-text -mlarge-text @gol -mmemory-latency=@var{time}} @emph{DEC Alpha/VMS Options} @@ -523,7 +542,7 @@ in the following sections. @gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300} @emph{SH Options} -@gccoptlist{-m1 -m2 -m3 -m3e @gol +@gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol -m4-nofpu -m4-single-only -m4-single -m4 @gol -m5-64media -m5-64media-nofpu @gol -m5-32media -m5-32media-nofpu @gol @@ -553,6 +572,7 @@ in the following sections. -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol -mapp-regs -mno-app-regs @gol -mdisable-callt -mno-disable-callt @gol +-mv850e1 @gol -mv850e @gol -mv850 -mbig-switch} @@ -593,9 +613,10 @@ in the following sections. -masm-optimize -mbranch-cost=@var{n} -mcond-exec=@var{n}} @emph{S/390 and zSeries Options} -@gccoptlist{-mhard-float -msoft-float -mbackchain -mno-backchain @gol --msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol --m64 -m31 -mdebug -mno-debug} +@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol +-mhard-float -msoft-float -mbackchain -mno-backchain @gol +-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol +-m64 -m31 -mdebug -mno-debug -mesa -mzarch -mfused-madd -mno-fused-madd} @emph{CRIS Options} @gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol @@ -603,7 +624,8 @@ in the following sections. -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol -mstack-align -mdata-align -mconst-align @gol -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol --melf -maout -melinux -mlinux -sim -sim2} +-melf -maout -melinux -mlinux -sim -sim2 @gol +-mmul-bug-workaround -mno-mul-bug-workaround} @emph{PDP-11 Options} @gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol @@ -617,36 +639,26 @@ in the following sections. @gccoptlist{-msim} @emph{Xtensa Options} -@gccoptlist{-mbig-endian -mlittle-endian @gol --mdensity -mno-density @gol --mmac16 -mno-mac16 @gol --mmul16 -mno-mul16 @gol --mmul32 -mno-mul32 @gol --mnsa -mno-nsa @gol --mminmax -mno-minmax @gol --msext -mno-sext @gol --mbooleans -mno-booleans @gol --mhard-float -msoft-float @gol +@gccoptlist{-mconst16 -mno-const16 @gol -mfused-madd -mno-fused-madd @gol --mserialize-volatile -mno-serialize-volatile @gol -mtext-section-literals -mno-text-section-literals @gol -mtarget-align -mno-target-align @gol -mlongcalls -mno-longcalls} @emph{FRV Options} @gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol --mhard-float -msoft-float -malloc-cc -mfixed-cc @gol --mdword -mno-dword -mdouble -mno-double @gol --mmedia -mno-media -mmuladd -mno-muladd -mlibrary-pic @gol --macc-4 -macc-8 -mpack -mno-pack -mno-eflags @gol --mcond-move -mno-cond-move -mscc -mno-scc @gol --mcond-exec -mno-cond-exec -mvliw-branch -mno-vliw-branch @gol +-mhard-float -msoft-float @gol +-malloc-cc -mfixed-cc -mdword -mno-dword @gol +-mdouble -mno-double @gol +-mmedia -mno-media -mmuladd -mno-muladd @gol +-mlibrary-pic -macc-4 -macc-8 @gol +-mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol +-mscc -mno-scc -mcond-exec -mno-cond-exec @gol +-mvliw-branch -mno-vliw-branch @gol -mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol -mno-nested-cond-exec -mtomcat-stats @gol -mcpu=@var{cpu}} - - @item Code Generation Options @xref{Code Gen Options,,Options for Code Generation Conventions}. @gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol @@ -654,17 +666,16 @@ in the following sections. -fnon-call-exceptions -funwind-tables @gol -fasynchronous-unwind-tables @gol -finhibit-size-directive -finstrument-functions @gol --fno-common -fno-ident -fno-gnu-linker @gol --fpcc-struct-return -fpic -fPIC @gol +-fno-common -fno-ident @gol +-fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol -freg-struct-return -fshared-data -fshort-enums @gol --fshort-double -fshort-wchar -fvolatile @gol --fvolatile-global -fvolatile-static @gol +-fshort-double -fshort-wchar @gol -fverbose-asm -fpack-struct -fstack-check @gol -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol -fargument-alias -fargument-noalias @gol -fargument-noalias-global -fleading-underscore @gol -ftls-model=@var{model} @gol --ftrapv -fbounds-check} +-ftrapv -fwrapv -fbounds-check} @end table @menu @@ -693,10 +704,12 @@ in the following sections. @section Options Controlling the Kind of Output Compilation can involve up to four stages: preprocessing, compilation -proper, assembly and linking, always in that order. The first three -stages apply to an individual source file, and end by producing an -object file; linking combines all the object files (those newly -compiled, and those specified as input) into an executable file. +proper, assembly and linking, always in that order. GCC is capable of +preprocessing and compiling several files either into several +assembler input files, or into one assembler input file; then each +assembler input file produces an object file, and linking combines all +the object files (those newly compiled, and those specified as input) +into an executable file. @cindex file name suffix For any given input file, the file name suffix determines what kind of @@ -720,18 +733,23 @@ Objective-C source code. Note that you must link with the library Objective-C source code which should not be preprocessed. @item @var{file}.h -C header file (not to be compiled or linked). +C or C++ header file to be turned into a precompiled header. @item @var{file}.cc @itemx @var{file}.cp @itemx @var{file}.cxx @itemx @var{file}.cpp +@itemx @var{file}.CPP @itemx @var{file}.c++ @itemx @var{file}.C C++ source code which must be preprocessed. Note that in @samp{.cxx}, the last two letters must both be literally @samp{x}. Likewise, @samp{.C} refers to a literal capital C@. +@item @var{file}.hh +@itemx @var{file}.H +C++ header file to be turned into a precompiled header. + @item @var{file}.f @itemx @var{file}.for @itemx @var{file}.FOR @@ -793,16 +811,16 @@ Specify explicitly the @var{language} for the following input files (rather than letting the compiler choose a default based on the file name suffix). This option applies to all following input files until the next @option{-x} option. Possible values for @var{language} are: -@example +@smallexample c c-header cpp-output -c++ c++-cpp-output -objective-c objc-cpp-output +c++ c++-header c++-cpp-output +objective-c objective-c-header objc-cpp-output assembler assembler-with-cpp ada f77 f77-cpp-input ratfor java treelang -@end example +@end smallexample @item -x none Turn off any specification of a language, so that subsequent files are @@ -863,9 +881,9 @@ Place output in file @var{file}. This applies regardless to whatever sort of output is being produced, whether it be an executable file, an object file, an assembler file or preprocessed C code. -Since only one output file can be specified, it does not make sense to -use @option{-o} when compiling more than one input file, unless you are -producing an executable file as output. +If you specify @option{-o} when compiling more than one input file, or +you are producing an executable file as output, all the source files +on the command line will be compiled at once. If @option{-o} is not specified, the default is to put an executable file in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in @@ -897,7 +915,7 @@ Print (on the standard output) a description of the command line options understood by @command{gcc}. If the @option{-v} option is also specified then @option{--help} will also be passed on to the various processes invoked by @command{gcc}, so that they can display the command line options -they accept. If the @option{-W} option is also specified then command +they accept. If the @option{-Wextra} option is also specified then command line options which have no documentation associated with them will also be displayed. @@ -917,22 +935,24 @@ Display the version number and copyrights of the invoked GCC. @cindex suffixes for C++ source @cindex C++ source file suffixes C++ source files conventionally use one of the suffixes @samp{.C}, -@samp{.cc}, @samp{.cpp}, @samp{.c++}, @samp{.cp}, or @samp{.cxx}; +@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or +@samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes files with these names and compiles them as C++ programs even if you -call the compiler the same way as for compiling C programs (usually with -the name @command{gcc}). +call the compiler the same way as for compiling C programs (usually +with the name @command{gcc}). @findex g++ @findex c++ However, C++ programs often require class libraries as well as a compiler that understands the C++ language---and under some -circumstances, you might want to compile programs from standard input, -or otherwise without a suffix that flags them as C++ programs. -@command{g++} is a program that calls GCC with the default language -set to C++, and automatically specifies linking against the C++ -library. On many systems, @command{g++} is also -installed with the name @command{c++}. +circumstances, you might want to compile programs or header files from +standard input, or otherwise without a suffix that flags them as C++ +programs. You might also like to precompile a C header file with a +@samp{.h} extension to be used in C++ compilations. @command{g++} is a +program that calls GCC with the default language set to C++, and +automatically specifies linking against the C++ library. On many +systems, @command{g++} is also installed with the name @command{c++}. @cindex invoking @command{g++} When you compile C++ programs, you may specify many of the same @@ -1013,14 +1033,14 @@ ISO C90 as modified in amendment 1. @itemx iso9899:1999 @itemx iso9899:199x ISO C99. Note that this standard is not yet fully supported; see -@w{@uref{http://gcc.gnu.org/gcc-3.3/c99status.html}} for more information. The +@w{@uref{http://gcc.gnu.org/gcc-3.4/c99status.html}} for more information. The names @samp{c9x} and @samp{iso9899:199x} are deprecated. @item gnu89 Default, ISO C90 plus GNU extensions (including some C99 features). @item gnu99 -@item gnu9x +@itemx gnu9x ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC, this will become the default. The name @samp{gnu9x} is deprecated. @@ -1216,6 +1236,8 @@ write into string constants. Writing into string constants is a very bad idea; ``constants'' should be constant. + +This option is deprecated. @end table @node C++ Dialect Options @@ -1229,9 +1251,9 @@ for C++ programs; but you can also use most of the GNU compiler options regardless of what language your program is in. For example, you might compile a file @code{firstClass.C} like this: -@example +@smallexample g++ -g -frepo -O -c firstClass.C -@end example +@end smallexample @noindent In this example, only @option{-frepo} is an option meant @@ -1244,13 +1266,14 @@ Here is a list of options that are @emph{only} for compiling C++ programs: @item -fabi-version=@var{n} @opindex fabi-version -Use version @var{n} of the C++ ABI. Version 1 is the version of the C++ -ABI that first appeared in G++ 3.2. Version 0 will always be the -version that conforms most closely to the C++ ABI specification. -Therefore, the ABI obtained using version 0 will change as ABI bugs are -fixed. +Use version @var{n} of the C++ ABI. Version 2 is the version of the +C++ ABI that first appeared in G++ 3.4. Version 1 is the version of +the C++ ABI that first appeared in G++ 3.2. Version 0 will always be +the version that conforms most closely to the C++ ABI specification. +Therefore, the ABI obtained using version 0 will change as ABI bugs +are fixed. -The default is version 1. +The default is version 2. @item -fno-access-control @opindex fno-access-control @@ -1293,14 +1316,6 @@ This option might be removed in a future release of G++. For maximum portability, you should structure your code so that it works with string constants that have type @code{const char *}. -@item -fdollars-in-identifiers -@opindex fdollars-in-identifiers -Accept @samp{$} in identifiers. You can also explicitly prohibit use of -@samp{$} with the option @option{-fno-dollars-in-identifiers}. (GNU C allows -@samp{$} by default on most target systems, but there are a few exceptions.) -Traditional C allowed the character @samp{$} to form part of -identifiers. However, ISO C and C++ forbid @samp{$} in identifiers. - @item -fno-elide-constructors @opindex fno-elide-constructors The C++ standard allows an implementation to omit creating a temporary @@ -1315,24 +1330,6 @@ option violates the C++ standard, but may be useful for reducing code size in production builds, much like defining @samp{NDEBUG}. The compiler will still optimize based on the exception specifications. -@item -fexternal-templates -@opindex fexternal-templates - -Cause @samp{#pragma interface} and @samp{implementation} to apply to -template instantiation; template instances are emitted or not according -to the location of the template definition. @xref{Template -Instantiation}, for more information. - -This option is deprecated. - -@item -falt-external-templates -@opindex falt-external-templates -Similar to @option{-fexternal-templates}, but template instances are -emitted or not according to the place where they are first instantiated. -@xref{Template Instantiation}, for more information. - -This option is deprecated. - @item -ffor-scope @itemx -fno-for-scope @opindex ffor-scope @@ -1437,17 +1434,6 @@ This option is required for fully standards-compliant handling of static destructors, but will only work if your C library supports @code{__cxa_atexit}. -@item -fvtable-gc -@opindex fvtable-gc -Emit special relocations for vtables and virtual function references -so that the linker can identify unused virtual functions and zero out -vtable slots that refer to them. This is most useful with -@option{-ffunction-sections} and @option{-Wl,--gc-sections}, in order to -also discard the functions themselves. - -This optimization requires GNU as and GNU ld. Not all systems support -this option. @option{-Wl,--gc-sections} is ignored without @option{-static}. - @item -fno-weak @opindex fno-weak Do not use weak symbol support, even if it is provided by the linker. @@ -1478,7 +1464,7 @@ inlined by default. @opindex Wabi Warn when G++ generates code that is probably not compatible with the vendor-neutral C++ ABI. Although an effort has been made to warn about -all such cases, there are probably some cases that are not warned about, +all such cases, there are probably some cases that are not warned about, even though G++ is generating incompatible code. There may also be cases where warnings are emitted even though the code that is generated will be compatible. @@ -1502,7 +1488,7 @@ struct B : public A @{ int f2 : 1; @}; @noindent In this case, G++ will place @code{B::f2} into the same byte -as@code{A::f1}; other compilers will not. You can avoid this problem +as@code{A::f1}; other compilers will not. You can avoid this problem by explicitly padding @code{A} so that its size is a multiple of the byte size on your platform; that will cause G++ and other compilers to layout @code{B} identically. @@ -1539,7 +1525,7 @@ union too small by the number of bits in an @code{int}. @item Empty classes can be placed at incorrect offsets. For example: - + @smallexample struct A @{@}; @@ -1577,7 +1563,7 @@ Instantiations of these templates may be mangled incorrectly. @opindex Wctor-dtor-privacy Warn when a class seems unusable because all the constructors or destructors in that class are private, and it has neither friends nor -public static member functions. This warning is enabled by default. +public static member functions. @item -Wnon-virtual-dtor @r{(C++ only)} @opindex Wnon-virtual-dtor @@ -1632,7 +1618,7 @@ Item 23: Don't try to return a reference when you must return an object. @end itemize -Also warn about violations of the following style guidelines from +Also warn about violations of the following style guidelines from Scott Meyers' @cite{More Effective C++} book: @itemize @bullet @@ -1711,7 +1697,7 @@ to a plain pointer. @item -Wsign-promo @r{(C++ only)} @opindex Wsign-promo Warn when overload resolution chooses a promotion from unsigned or -enumeral type to a signed type, over a conversion to an unsigned type of +enumerated type to a signed type, over a conversion to an unsigned type of the same size. Previous versions of G++ would try to preserve unsignedness, but the standard mandates the current behavior. @@ -1745,14 +1731,17 @@ In this example, G++ will synthesize a default @samp{A& operator = @cindex compiler options, Objective-C @cindex Objective-C options, command line @cindex options, Objective-C +(NOTE: This manual does not describe the Objective-C language itself. See +@w{@uref{http://gcc.gnu.org/readings.html}} for references.) + This section describes the command-line options that are only meaningful for Objective-C programs, but you can also use most of the GNU compiler options regardless of what language your program is in. For example, you might compile a file @code{some_class.m} like this: -@example +@smallexample gcc -g -fgnu-runtime -O -c some_class.m -@end example +@end smallexample @noindent In this example, @option{-fgnu-runtime} is an option meant only for @@ -1767,7 +1756,11 @@ programs: @opindex fconstant-string-class Use @var{class-name} as the name of the class to instantiate for each literal string specified with the syntax @code{@@"@dots{}"}. The default -class name is @code{NXConstantString}. +class name is @code{NXConstantString} if the GNU runtime is being used, and +@code{NSConstantString} if the NeXT runtime is being used (see below). The +@option{-fconstant-cfstrings} option, if also present, will override the +@option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals +to be laid out as constant CoreFoundation strings. @item -fgnu-runtime @opindex fgnu-runtime @@ -1781,6 +1774,127 @@ for NeXT-based systems, including Darwin and Mac OS X@. The macro @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is used. +@item -fno-nil-receivers +@opindex fno-nil-receivers +Assume that all Objective-C message dispatches (e.g., +@code{[receiver message:arg]}) in this translation unit ensure that the receiver +is not @code{nil}. This allows for more efficient entry points in the runtime to be +used. Currently, this option is only available in conjunction with +the NeXT runtime on Mac OS X 10.3 and later. + +@item -fobjc-exceptions +@opindex fobjc-exceptions +Enable syntactic support for structured exception handling in Objective-C, +similar to what is offered by C++ and Java. Currently, this option is only +available in conjunction with the NeXT runtime on Mac OS X 10.3 and later. + +@smallexample + @@try @{ + @dots{} + @@throw expr; + @dots{} + @} + @@catch (AnObjCClass *exc) @{ + @dots{} + @@throw expr; + @dots{} + @@throw; + @dots{} + @} + @@catch (AnotherClass *exc) @{ + @dots{} + @} + @@catch (id allOthers) @{ + @dots{} + @} + @@finally @{ + @dots{} + @@throw expr; + @dots{} + @} +@end smallexample + +The @code{@@throw} statement may appear anywhere in an Objective-C or +Objective-C++ program; when used inside of a @code{@@catch} block, the +@code{@@throw} may appear without an argument (as shown above), in which case +the object caught by the @code{@@catch} will be rethrown. + +Note that only (pointers to) Objective-C objects may be thrown and +caught using this scheme. When an object is thrown, it will be caught +by the nearest @code{@@catch} clause capable of handling objects of that type, +analogously to how @code{catch} blocks work in C++ and Java. A +@code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch +any and all Objective-C exceptions not caught by previous @code{@@catch} +clauses (if any). + +The @code{@@finally} clause, if present, will be executed upon exit from the +immediately preceding @code{@@try @dots{} @@catch} section. This will happen +regardless of whether any exceptions are thrown, caught or rethrown +inside the @code{@@try @dots{} @@catch} section, analogously to the behavior +of the @code{finally} clause in Java. + +There are several caveats to using the new exception mechanism: + +@itemize @bullet +@item +Although currently designed to be binary compatible with @code{NS_HANDLER}-style +idioms provided by the @code{NSException} class, the new +exceptions can only be used on Mac OS X 10.3 (Panther) and later +systems, due to additional functionality needed in the (NeXT) Objective-C +runtime. + +@item +As mentioned above, the new exceptions do not support handling +types other than Objective-C objects. Furthermore, when used from +Objective-C++, the Objective-C exception model does not interoperate with C++ +exceptions at this time. This means you cannot @code{@@throw} an exception +from Objective-C and @code{catch} it in C++, or vice versa +(i.e., @code{throw @dots{} @@catch}). +@end itemize + +The @option{-fobjc-exceptions} switch also enables the use of synchronization +blocks for thread-safe execution: + +@smallexample + @@synchronized (ObjCClass *guard) @{ + @dots{} + @} +@end smallexample + +Upon entering the @code{@@synchronized} block, a thread of execution shall +first check whether a lock has been placed on the corresponding @code{guard} +object by another thread. If it has, the current thread shall wait until +the other thread relinquishes its lock. Once @code{guard} becomes available, +the current thread will place its own lock on it, execute the code contained in +the @code{@@synchronized} block, and finally relinquish the lock (thereby +making @code{guard} available to other threads). + +Unlike Java, Objective-C does not allow for entire methods to be marked +@code{@@synchronized}. Note that throwing exceptions out of +@code{@@synchronized} blocks is allowed, and will cause the guarding object +to be unlocked properly. + +@item -freplace-objc-classes +@opindex freplace-objc-classes +Emit a special marker instructing @command{ld(1)} not to statically link in +the resulting object file, and allow @command{dyld(1)} to load it in at +run time instead. This is used in conjunction with the Fix-and-Continue +debugging mode, where the object file in question may be recompiled and +dynamically reloaded in the course of program execution, without the need +to restart the program itself. Currently, Fix-and-Continue functionality +is only available in conjunction with the NeXT runtime on Mac OS X 10.3 +and later. + +@item -fzero-link +@opindex fzero-link +When compiling for the NeXT runtime, the compiler ordinarily replaces calls +to @code{objc_getClass("@dots{}")} (when the name of the class is known at +compile time) with static class references that get initialized at load time, +which improves run-time performance. Specifying the @option{-fzero-link} flag +suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")} +to be retained. This is useful in Zero-Link debugging mode, since it allows +for individual class implementations to be modified during program execution. + @item -gen-decls @opindex gen-decls Dump interface declarations for all classes seen in the source file to a @@ -1813,7 +1927,7 @@ being used. @opindex Wundeclared-selector Warn if a @code{@@selector(@dots{})} expression referring to an undeclared selector is found. A selector is considered undeclared if no -method with that name has been declared before the +method with that name has been declared before the @code{@@selector(@dots{})} expression, either explicitly in an @code{@@interface} or @code{@@protocol} declaration, or implicitly in an @code{@@implementation} section. This option always performs its @@ -1822,8 +1936,10 @@ while @code{-Wselector} only performs its checks in the final stage of compilation. This also enforces the coding style convention that methods and selectors must be declared before being used. -@c not documented because only avail via -Wp -@c @item -print-objc-runtime-info +@item -print-objc-runtime-info +@opindex print-objc-runtime-info +Generate C header describing the largest structure that is passed by +value, if any. @end table @@ -1985,14 +2101,14 @@ Since @option{-Wformat} also checks for null format arguments for several functions, @option{-Wformat} also implies @option{-Wnonnull}. @option{-Wformat} is included in @option{-Wall}. For more control over some -aspects of format checking, the options @option{-Wno-format-y2k}, +aspects of format checking, the options @option{-Wformat-y2k}, @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length}, @option{-Wformat-nonliteral}, @option{-Wformat-security}, and @option{-Wformat=2} are available, but are not included in @option{-Wall}. -@item -Wno-format-y2k -@opindex Wno-format-y2k -If @option{-Wformat} is specified, do not warn about @code{strftime} +@item -Wformat-y2k +@opindex Wformat-y2k +If @option{-Wformat} is specified, also warn about @code{strftime} formats which may yield only a two-digit year. @item -Wno-format-extra-args @@ -2036,16 +2152,34 @@ included in @option{-Wformat-nonliteral}.) @opindex Wformat=2 Enable @option{-Wformat} plus format checks not included in @option{-Wformat}. Currently equivalent to @samp{-Wformat --Wformat-nonliteral -Wformat-security}. +-Wformat-nonliteral -Wformat-security -Wformat-y2k}. @item -Wnonnull @opindex Wnonnull -Enable warning about passing a null pointer for arguments marked as +Warn about passing a null pointer for arguments marked as requiring a non-null value by the @code{nonnull} function attribute. @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It can be disabled with the @option{-Wno-nonnull} option. +@item -Winit-self @r{(C, C++, and Objective-C only)} +@opindex Winit-self +Warn about uninitialized variables which are initialized with themselves. +Note this option can only be used with the @option{-Wuninitialized} option, +which in turn only works with @option{-O1} and above. + +For example, GCC will warn about @code{i} being uninitialized in the +following snippet only when @option{-Winit-self} has been specified: +@smallexample +@group +int f() +@{ + int i = i; + return i; +@} +@end group +@end smallexample + @item -Wimplicit-int @opindex Wimplicit-int Warn when a declaration does not specify a type. @@ -2167,7 +2301,7 @@ future implementation may also work for C++ programs. The C standard is worded confusingly, therefore there is some debate over the precise meaning of the sequence point rules in subtle cases. Links to discussions of the problem, including proposed formal -definitions, may be found on our readings page, at +definitions, may be found on the GCC readings page, at @w{@uref{http://gcc.gnu.org/readings.html}}. @item -Wreturn-type @@ -2182,7 +2316,7 @@ exceptions are @samp{main} and functions defined in system headers. @item -Wswitch @opindex Wswitch -Warn whenever a @code{switch} statement has an index of enumeral type +Warn whenever a @code{switch} statement has an index of enumerated type and lacks a @code{case} for one or more of the named codes of that enumeration. (The presence of a @code{default} label prevents this warning.) @code{case} labels outside the enumeration range also @@ -2195,7 +2329,7 @@ case. @item -Wswitch-enum @opindex Wswitch-enum -Warn whenever a @code{switch} statement has an index of enumeral type +Warn whenever a @code{switch} statement has an index of enumerated type and lacks a @code{case} for one or more of the named codes of that enumeration. @code{case} labels outside the enumeration range also provoke warnings when this option is used. @@ -2243,8 +2377,8 @@ To suppress this warning cast the expression to @samp{void}. All the above @option{-Wunused} options combined. In order to get a warning about an unused function parameter, you must -either specify @samp{-W -Wunused} or separately specify -@option{-Wunused-parameter}. +either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies +@samp{-Wunused}), or separately specify @option{-Wunused-parameter}. @item -Wuninitialized @opindex Wuninitialized @@ -2256,6 +2390,9 @@ because they require data flow information that is computed only when optimizing. If you don't specify @option{-O}, you simply won't get these warnings. +If you want to warn about code which uses the uninitialized value of the +variable in its own initializer, use the @option{-Winit-self} option. + These warnings occur only for variables that are candidates for register allocation. Therefore, they do not occur for a variable that is declared @code{volatile}, or whose address is taken, or whose size @@ -2357,9 +2494,12 @@ in some cases, and there is no simple way to modify the code to suppress the warning. @table @gcctabopt -@item -W +@item -Wextra @opindex W -Print extra warning messages for these events: +@opindex Wextra +(This option used to be called @option{-W}. The older name is still +supported, but the newer name is more descriptive.) Print extra warning +messages for these events: @itemize @bullet @item @@ -2414,17 +2554,6 @@ incorrect result when the signed value is converted to unsigned. (But don't warn if @option{-Wno-sign-compare} is also specified.) @item -An aggregate has a partly bracketed initializer. -For example, the following code would evoke such a warning, -because braces are missing around the initializer for @code{x.h}: - -@smallexample -struct s @{ int f, g; @}; -struct t @{ struct s h; int i; @}; -struct t x = @{ 1, 2, 3 @}; -@end smallexample - -@item An aggregate has an initializer which does not initialize all members. For example, the following code would cause such a warning, because @code{x.h} would be implicitly initialized to zero: @@ -2433,6 +2562,47 @@ For example, the following code would cause such a warning, because struct s @{ int f, g, h; @}; struct s x = @{ 3, 4 @}; @end smallexample + +@item +A function parameter is declared without a type specifier in K&R-style +functions: + +@smallexample +void foo(bar) @{ @} +@end smallexample + +@item +An empty body occurs in an @samp{if} or @samp{else} statement. + +@item +A pointer is compared against integer zero with @samp{<}, @samp{<=}, +@samp{>}, or @samp{>=}. + +@item +A variable might be changed by @samp{longjmp} or @samp{vfork}. + +@item +Any of several floating-point events that often indicate errors, such as +overflow, underflow, loss of precision, etc. + +@item @r{(C++ only)} +An enumerator and a non-enumerator both appear in a conditional expression. + +@item @r{(C++ only)} +A non-static reference or non-static @samp{const} member appears in a +class without constructors. + +@item @r{(C++ only)} +Ambiguous virtual bases. + +@item @r{(C++ only)} +Subscripting an array which has been declared @samp{register}. + +@item @r{(C++ only)} +Taking the address of a variable which has been declared @samp{register}. + +@item @r{(C++ only)} +A base class is not initialized in a derived class' copy constructor. @end itemize @item -Wno-div-by-zero @@ -2505,7 +2675,7 @@ constant suffixes. (Traditional C does support the @samp{L} suffix on integer constants.) Note, these suffixes appear in macros defined in the system headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}. Use of these macros in user code might normally lead to spurious -warnings, however gcc's integrated preprocessor has enough context to +warnings, however GCC's integrated preprocessor has enough context to avoid warning in these cases. @item @@ -2554,10 +2724,17 @@ Use of ISO C style function definitions. This warning intentionally is because these ISO C features will appear in your code when using libiberty's traditional C compatibility macros, @code{PARAMS} and @code{VPARAMS}. This warning is also bypassed for nested functions -because that feature is already a gcc extension and thus not relevant to +because that feature is already a GCC extension and thus not relevant to traditional C compatibility. @end itemize +@item -Wdeclaration-after-statement @r{(C only)} +@opindex Wdeclaration-after-statement +Warn when a declaration is found after a statement in a block. This +construct, known from C++, was introduced with ISO C99 and is by default +allowed in GCC@. It is not supported by ISO C90 and was not supported by +GCC versions before GCC 3.0. @xref{Mixed Declarations}. + @item -Wundef @opindex Wundef Warn if an undefined identifier is evaluated in an @samp{#if} directive. @@ -2633,8 +2810,8 @@ casts like @code{(unsigned) -1}. @cindex signed and unsigned values, comparison warning Warn when a comparison between signed and unsigned values could produce an incorrect result when the signed value is converted to unsigned. -This warning is enabled by @option{-W}, and by @option{-Wall} -in C++ only. +This warning is also enabled by @option{-Wextra}; to get the other warnings +of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}. @item -Waggregate-return @opindex Waggregate-return @@ -2649,6 +2826,11 @@ argument types. (An old-style function definition is permitted without a warning if preceded by a declaration which specifies the argument types.) +@item -Wold-style-definition @r{(C only)} +@opindex Wold-style-definition +Warn if an old-style function definition is used. A warning is given +even if there is a previous prototype. + @item -Wmissing-prototypes @r{(C only)} @opindex Wmissing-prototypes Warn if a global function is defined without a previous prototype @@ -2762,7 +2944,7 @@ code is to provide behavior which is selectable at compile-time. @opindex Winline Warn if a function can not be inlined and it was declared as inline. Even with this option, the compiler will not warn about failures to -inline functions declared in system headers. +inline functions declared in system headers. The compiler uses a variety of heuristics to determine whether or not to inline a function. For example, the compiler takes into account @@ -2771,6 +2953,26 @@ that has already been done in the current function. Therefore, seemingly insignificant changes in the source program can cause the warnings produced by @option{-Winline} to appear or disappear. +@item -Wno-invalid-offsetof @r{(C++ only)} +@opindex Wno-invalid-offsetof +Suppress warnings from applying the @samp{offsetof} macro to a non-POD +type. According to the 1998 ISO C++ standard, applying @samp{offsetof} +to a non-POD type is undefined. In existing C++ implementations, +however, @samp{offsetof} typically gives meaningful results even when +applied to certain kinds of non-POD types. (Such as a simple +@samp{struct} that fails to be a POD type only by virtue of having a +constructor.) This flag is for users who are aware that they are +writing nonportable code and who have deliberately chosen to ignore the +warning about it. + +The restrictions on @samp{offsetof} may be relaxed in a future version +of the C++ standard. + +@item -Winvalid-pch +@opindex Winvalid-pch +Warn if a precompiled header (@pxref{Precompiled Headers}) is found in +the search path but can't be used. + @item -Wlong-long @opindex Wlong-long @opindex Wno-long-long @@ -2814,8 +3016,7 @@ makes debugging work better in GDB but will probably make other debuggers crash or refuse to read the program. If you want to control for certain whether to generate the extra information, use @option{-gstabs+}, @option{-gstabs}, -@option{-gxcoff+}, @option{-gxcoff}, @option{-gdwarf-1+}, @option{-gdwarf-1}, -or @option{-gvms} (see below). +@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below). Unlike most other C compilers, GCC allows you to use @option{-g} with @option{-O}. The shortcuts taken by optimized code may occasionally @@ -2846,6 +3047,11 @@ systems. On MIPS, Alpha and System V Release 4 systems this option produces stabs debugging output which is not understood by DBX or SDB@. On System V Release 4 systems this option requires the GNU assembler. +@item -feliminate-unused-debug-symbols +@opindex feliminate-unused-debug-symbols +Produce debugging information in stabs format (if that is supported), +for only symbols that are actually used. + @item -gstabs+ @opindex gstabs+ Produce debugging information in stabs format (if that is supported), @@ -2872,23 +3078,6 @@ use of these extensions is likely to make other debuggers crash or refuse to read the program, and may cause assemblers other than the GNU assembler (GAS) to fail with an error. -@item -gdwarf -@opindex gdwarf -Produce debugging information in DWARF version 1 format (if that is -supported). This is the format used by SDB on most System V Release 4 -systems. - -This option is deprecated. - -@item -gdwarf+ -@opindex gdwarf+ -Produce debugging information in DWARF version 1 format (if that is -supported), using GNU extensions understood only by the GNU debugger -(GDB)@. The use of these extensions is likely to make other debuggers -crash or refuse to read the program. - -This option is deprecated. - @item -gdwarf-2 @opindex gdwarf-2 Produce debugging information in DWARF version 2 format (if that is @@ -2918,9 +3107,9 @@ present in the program. Some debuggers support macro expansion when you use @option{-g3}. Note that in order to avoid confusion between DWARF1 debug level 2, -and DWARF2, neither @option{-gdwarf} nor @option{-gdwarf-2} accept -a concatenated debug level. Instead use an additional @option{-g@var{level}} -option to change the debug level for DWARF1 or DWARF2. +and DWARF2 @option{-gdwarf-2} does not accept a concatenated debug +level. Instead use an additional @option{-g@var{level}} option to +change the debug level for DWARF2. @item -feliminate-dwarf2-dups @opindex feliminate-dwarf2-dups @@ -2961,27 +3150,51 @@ allocation when it finishes. @item -fprofile-arcs @opindex fprofile-arcs -Instrument @dfn{arcs} during compilation to generate coverage data or -for profile-directed block ordering. During execution the program -records how many times each branch is executed and how many times it is -taken. When the compiled program exits it saves this data to a file -called @file{@var{auxname}.da} for each source file. @var{auxname} is -generated from the name of the output file, if explicitly specified and -it is not the final executable, otherwise it is the basename of the -source file. In both cases any suffix is removed (e.g. @file{foo.da} -for input file @file{dir/foo.c}, or @file{dir/foo.da} for output file -specified as @option{-o dir/foo.o}). - -For profile-directed block ordering, compile the program with -@option{-fprofile-arcs} plus optimization and code generation options, -generate the arc profile information by running the program on a -selected workload, and then compile the program again with the same -optimization and code generation options plus +Add code so that program flow @dfn{arcs} are instrumented. During +execution the program records how many times each branch and call is +executed and how many times it is taken or returns. When the compiled +program exits it saves this data to a file called +@file{@var{auxname}.gcda} for each source file. The data may be used for +profile-directed optimizations (@option{-fbranch-probabilities}), or for +test coverage analysis (@option{-ftest-coverage}). Each object file's +@var{auxname} is generated from the name of the output file, if +explicitly specified and it is not the final executable, otherwise it is +the basename of the source file. In both cases any suffix is removed +(e.g. @file{foo.gcda} for input file @file{dir/foo.c}, or +@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}). + +@itemize + +@item +Compile the source files with @option{-fprofile-arcs} plus optimization +and code generation options. For test coverage analysis, use the +additional @option{-ftest-coverage} option. You do not need to profile +every source file in a program. + +@item +Link your object files with @option{-lgcov} or @option{-fprofile-arcs} +(the latter implies the former). + +@item +Run the program on a representative workload to generate the arc profile +information. This may be repeated any number of times. You can run +concurrent instances of your program, and provided that the file system +supports locking, the data files will be correctly updated. Also +@code{fork} calls are detected and correctly handled (double counting +will not happen). + +@item +For profile-directed optimizations, compile the source files again with +the same optimization and code generation options plus @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that Control Optimization}). -The other use of @option{-fprofile-arcs} is for use with @command{gcov}, -when it is used with the @option{-ftest-coverage} option. +@item +For test coverage analysis, use @command{gcov} to produce human readable +information from the @file{.gcno} and @file{.gcda} files. Refer to the +@command{gcov} documentation for further information. + +@end itemize With @option{-fprofile-arcs}, for each function of your program GCC creates a program flow graph, then finds a spanning tree for the graph. @@ -2994,34 +3207,13 @@ block must be created to hold the instrumentation code. @need 2000 @item -ftest-coverage @opindex ftest-coverage -Create data files for the @command{gcov} code-coverage utility -(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}). See -@option{-fprofile-arcs} option above for a description of @var{auxname}. - -@table @gcctabopt -@item @var{auxname}.bb -A mapping from basic blocks to line numbers, which @command{gcov} uses to -associate basic block execution counts with line numbers. - -@item @var{auxname}.bbg -A list of all arcs in the program flow graph. This allows @command{gcov} -to reconstruct the program flow graph, so that it can compute all basic -block and arc execution counts from the information in the -@file{@var{auxname}.da} file. -@end table - -Use @option{-ftest-coverage} with @option{-fprofile-arcs}; the latter -option adds instrumentation to the program, which then writes -execution counts to another data file: - -@table @gcctabopt -@item @var{auxname}.da -Runtime arc execution counts, used in conjunction with the arc -information in the file @file{@var{auxname}.bbg}. -@end table - -Coverage data will map better to the source files if -@option{-ftest-coverage} is used without optimization. +Produce a notes file that the @command{gcov} code-coverage utility +(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to +show program coverage. Each source file's note file is called +@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option +above for a description of @var{auxname} and instructions on how to +generate test coverage data. Coverage data will match the source files +more closely, if you do not optimize. @item -d@var{letters} @opindex d @@ -3031,7 +3223,7 @@ for most of the dumps are made by appending a pass number and a word to the @var{dumpname}. @var{dumpname} is generated from the name of the output file, if explicitly specified and it is not an executable, otherwise it is the basename of the source file. In both cases any -suffix is removed (e.g. @file{foo.00.rtl} or @file{foo.01.sibling}). +suffix is removed (e.g. @file{foo.01.rtl} or @file{foo.02.sibling}). Here are the possible letters for use in @var{letters}, and their meanings: @@ -3041,113 +3233,119 @@ meanings: Annotate the assembler output with miscellaneous debugging information. @item b @opindex db -Dump after computing branch probabilities, to @file{@var{file}.14.bp}. +Dump after computing branch probabilities, to @file{@var{file}.12.bp}. @item B @opindex dB -Dump after block reordering, to @file{@var{file}.32.bbro}. +Dump after block reordering, to @file{@var{file}.31.bbro}. @item c @opindex dc -Dump after instruction combination, to the file @file{@var{file}.19.combine}. +Dump after instruction combination, to the file @file{@var{file}.20.combine}. @item C @opindex dC -Dump after the first if conversion, to the file @file{@var{file}.15.ce1}. +Dump after the first if conversion, to the file @file{@var{file}.14.ce1}. +Also dump after the second if conversion, to the file @file{@var{file}.21.ce2}. @item d @opindex dd -Dump after delayed branch scheduling, to @file{@var{file}.34.dbr}. +Dump after branch target load optimization, to to @file{@var{file}.32.btl}. +Also dump after delayed branch scheduling, to @file{@var{file}.36.dbr}. @item D @opindex dD Dump all macro definitions, at the end of preprocessing, in addition to normal output. -@item e -@opindex de -Dump after SSA optimizations, to @file{@var{file}.04.ssa} and -@file{@var{file}.07.ussa}. @item E @opindex dE -Dump after the second if conversion, to @file{@var{file}.29.ce3}. +Dump after the third if conversion, to @file{@var{file}.30.ce3}. @item f @opindex df -Dump after control and data flow analysis, to @file{@var{file}.14.cfg}. -Also dump after life analysis, to @file{@var{file}.18.life}. +Dump after control and data flow analysis, to @file{@var{file}.11.cfg}. +Also dump after life analysis, to @file{@var{file}.19.life}. @item F @opindex dF -Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.10.addressof}. +Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.07.addressof}. @item g @opindex dg -Dump after global register allocation, to @file{@var{file}.24.greg}. +Dump after global register allocation, to @file{@var{file}.25.greg}. @item G @opindex dG -Dump after GCSE, to @file{@var{file}.11.gcse}. +Dump after GCSE, to @file{@var{file}.08.gcse}. +Also dump after jump bypassing and control flow optimizations, to +@file{@var{file}.10.bypass}. @item h @opindex dh -Dump after finalization of EH handling code, to @file{@var{file}.02.eh}. +Dump after finalization of EH handling code, to @file{@var{file}.03.eh}. @item i @opindex di -Dump after sibling call optimizations, to @file{@var{file}.01.sibling}. +Dump after sibling call optimizations, to @file{@var{file}.02.sibling}. @item j @opindex dj -Dump after the first jump optimization, to @file{@var{file}.03.jump}. +Dump after the first jump optimization, to @file{@var{file}.04.jump}. @item k @opindex dk -Dump after conversion from registers to stack, to @file{@var{file}.31.stack}. +Dump after conversion from registers to stack, to @file{@var{file}.34.stack}. @item l @opindex dl -Dump after local register allocation, to @file{@var{file}.23.lreg}. +Dump after local register allocation, to @file{@var{file}.24.lreg}. @item L @opindex dL -Dump after loop optimization, to @file{@var{file}.12.loop}. +Dump after loop optimization passes, to @file{@var{file}.09.loop} and +@file{@var{file}.16.loop2}. @item M @opindex dM Dump after performing the machine dependent reorganization pass, to -@file{@var{file}.33.mach}. +@file{@var{file}.35.mach}. @item n @opindex dn -Dump after register renumbering, to @file{@var{file}.28.rnreg}. +Dump after register renumbering, to @file{@var{file}.29.rnreg}. @item N @opindex dN -Dump after the register move pass, to @file{@var{file}.21.regmove}. +Dump after the register move pass, to @file{@var{file}.22.regmove}. @item o @opindex do -Dump after post-reload optimizations, to @file{@var{file}.25.postreload}. +Dump after post-reload optimizations, to @file{@var{file}.26.postreload}. @item r @opindex dr -Dump after RTL generation, to @file{@var{file}.00.rtl}. +Dump after RTL generation, to @file{@var{file}.01.rtl}. @item R @opindex dR -Dump after the second scheduling pass, to @file{@var{file}.30.sched2}. +Dump after the second scheduling pass, to @file{@var{file}.33.sched2}. @item s @opindex ds Dump after CSE (including the jump optimization that sometimes follows -CSE), to @file{@var{file}.09.cse}. +CSE), to @file{@var{file}.06.cse}. @item S @opindex dS -Dump after the first scheduling pass, to @file{@var{file}.22.sched}. +Dump after the first scheduling pass, to @file{@var{file}.23.sched}. @item t @opindex dt Dump after the second CSE pass (including the jump optimization that -sometimes follows CSE), to @file{@var{file}.17.cse2}. +sometimes follows CSE), to @file{@var{file}.18.cse2}. @item T @opindex dT -Dump after running tracer, to @file{@var{file}.16.tracer}. +Dump after running tracer, to @file{@var{file}.15.tracer}. @item u @opindex du -Dump after null pointer elimination pass to @file{@var{file}.08.null}. +Dump after null pointer elimination pass to @file{@var{file}.05.null}. +@item U +@opindex dU +Dump callgraph and unit-at-a-time optimization @file{@var{file}.00.unit}. +@item V +@opindex dV +Dump after the value profile transformations, to @file{@var{file}.13.vpt}. @item w @opindex dw -Dump after the second flow pass, to @file{@var{file}.26.flow2}. -@item W -@opindex dW -Dump after SSA conditional constant propagation, to -@file{@var{file}.05.ssaccp}. -@item X -@opindex dX -Dump after SSA dead code elimination, to @file{@var{file}.06.ssadce}. +Dump after the second flow pass, to @file{@var{file}.27.flow2}. @item z @opindex dz -Dump after the peephole pass, to @file{@var{file}.27.peephole2}. +Dump after the peephole pass, to @file{@var{file}.28.peephole2}. +@item Z +@opindex dZ +Dump after constructing the web, to @file{@var{file}.17.web}. @item a @opindex da Produce all the dumps listed above. +@item H +@opindex dH +Produce a core dump whenever an error occurs. @item m @opindex dm Print statistics on memory usage, at the end of the run, to @@ -3164,7 +3362,7 @@ Also turns on @option{-dp} annotation. @item v @opindex dv For each of the other indicated dump files (except for -@file{@var{file}.00.rtl}), dump a representation of the control flow graph +@file{@var{file}.01.rtl}), dump a representation of the control flow graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}. @item x @opindex dx @@ -3237,8 +3435,11 @@ Dump after function inlining, to @file{@var{file}.inlined}. @item -frandom-seed=@var{string} @opindex frandom-string This option provides a seed that GCC uses when it would otherwise use -random numbers. At present, this is used to generate certain symbol names -that have to be different in every compiled file. +random numbers. It is used to generate certain symbol names +that have to be different in every compiled file. It is also used to +place unique stamps in coverage data files and the object files that +produce them. You can use the @option{-frandom-seed} option to produce +reproducibly identical object files. The @var{string} should be different for every file you compile. @@ -3316,19 +3517,19 @@ Same as @option{-print-file-name=libgcc.a}. This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs} but you do want to link with @file{libgcc.a}. You can do -@example +@smallexample gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name` -@end example +@end smallexample @item -print-search-dirs @opindex print-search-dirs Print the name of the configured installation directory and a list of -program and library directories gcc will search---and don't do anything else. +program and library directories @command{gcc} will search---and don't do anything else. -This is useful when gcc prints the error message +This is useful when @command{gcc} prints the error message @samp{installation problem, cannot exec cpp0: No such file or directory}. To resolve this you either need to put @file{cpp0} and the other compiler -components where gcc expects to find them, or you can set the environment +components where @command{gcc} expects to find them, or you can set the environment variable @env{GCC_EXEC_PREFIX} to the directory where you installed them. Don't forget the trailing '/'. @xref{Environment Variables}. @@ -3347,6 +3548,18 @@ anything else. @opindex dumpspecs Print the compiler's built-in specs---and don't do anything else. (This is used when GCC itself is being built.) @xref{Spec Files}. + +@item -feliminate-unused-debug-types +@opindex feliminate-unused-debug-types +Normally, when producing DWARF2 output, GCC will emit debugging +information for all types declared in a compilation +unit, regardless of whether or not they are actually used +in that compilation unit. Sometimes this is useful, such as +if, in the debugger, you want to cast a value to a type that is +not actually used in your program (but is declared). More often, +however, this results in a significant amount of wasted space. +With this option, GCC will avoid producing debug symbol output +for types that are nowhere used in the source file being compiled. @end table @node Optimize Options @@ -3368,6 +3581,14 @@ Turning on optimization flags makes the compiler attempt to improve the performance and/or code size at the expense of compilation time and possibly the ability to debug the program. +The compiler performs optimization based on the knowledge it has of +the program. Using the @option{-funit-at-a-time} flag will allow the +compiler to consider information gained from later functions in the +file when compiling a function. Compiling multiple files at once to a +single output file (and using @option{-funit-at-a-time}) will allow +the compiler to use information gained from all of the files when +compiling each of them. + Not all optimizations are controlled directly by a flag. Only optimizations that have a flag are listed. @@ -3383,12 +3604,11 @@ With @option{-O}, the compiler tries to reduce code size and execution time, without performing any optimizations that take a great deal of compilation time. -@option{-O} turns on the following optimization flags: +@option{-O} turns on the following optimization flags: @gccoptlist{-fdefer-pop @gol -fmerge-constants @gol -fthread-jumps @gol -floop-optimize @gol --fcrossjumping @gol -fif-conversion @gol -fif-conversion2 @gol -fdelayed-branch @gol @@ -3413,18 +3633,20 @@ also turns on the following optimization flags: -fstrength-reduce @gol -fcse-follow-jumps -fcse-skip-blocks @gol -frerun-cse-after-loop -frerun-loop-opt @gol --fgcse -fgcse-lm -fgcse-sm @gol +-fgcse -fgcse-lm -fgcse-sm -fgcse-las @gol -fdelete-null-pointer-checks @gol -fexpensive-optimizations @gol -fregmove @gol -fschedule-insns -fschedule-insns2 @gol --fsched-interblock -fsched-spec @gol +-fsched-interblock -fsched-spec @gol -fcaller-saves @gol -fpeephole2 @gol -freorder-blocks -freorder-functions @gol -fstrict-aliasing @gol +-funit-at-a-time @gol -falign-functions -falign-jumps @gol --falign-loops -falign-labels} +-falign-loops -falign-labels @gol +-fcrossjumping} Please note the warning under @option{-fgcse} about invoking @option{-O2} on programs that use computed gotos. @@ -3432,8 +3654,8 @@ invoking @option{-O2} on programs that use computed gotos. @item -O3 @opindex O3 Optimize yet more. @option{-O3} turns on all optimizations specified by -@option{-O2} and also turns on the @option{-finline-functions} and -@option{-frename-registers} options. +@option{-O2} and also turns on the @option{-finline-functions}, +@option{-fweb} and @option{-frename-registers} options. @item -O0 @opindex O0 @@ -3542,7 +3764,7 @@ Enabled at level @option{-O3}. @item -finline-limit=@var{n} @opindex finline-limit -By default, gcc limits the size of functions that can be inlined. This flag +By default, GCC limits the size of functions that can be inlined. This flag allows the control of this limit for functions that are explicitly marked as inline (i.e., marked with the inline keyword or defined within the class definition in c++). @var{n} is the size of functions that can be inlined in @@ -3556,12 +3778,10 @@ use inlining heavily such as those based on recursive templates with C++. Inlining is actually controlled by a number of parameters, which may be specified individually by using @option{--param @var{name}=@var{value}}. -The @option{-finline-limit=@var{n}} option sets some of these parameters +The @option{-finline-limit=@var{n}} option sets some of these parameters as follows: @table @gcctabopt - @item max-inline-insns - is set to @var{n}. @item max-inline-insns-single is set to @var{n}/2. @item max-inline-insns-auto @@ -3572,8 +3792,7 @@ as follows: is set to @var{n}. @end table -Using @option{-finline-limit=600} thus results in the default settings -for these parameters. See below for a documentation of the individual +See below for a documentation of the individual parameters controlling inlining. @emph{Note:} pseudo instruction represents, in this particular context, an @@ -3617,6 +3836,12 @@ types. Languages like C or C++ require each non-automatic variable to have distinct location, so using this option will result in non-conforming behavior. +@item -fnew-ra +@opindex fnew-ra +Use a graph coloring register allocator. Currently this option is meant +only for testing. Users should not specify this option, since it is not +yet ready for production use. + @item -fno-branch-count-reg @opindex fno-branch-count-reg Do not use ``decrement and branch'' instructions on a count register, @@ -3725,10 +3950,19 @@ Enabled by default when gcse is enabled. @item -fgcse-sm @opindex fgcse-sm -When @option{-fgcse-sm} is enabled, A store motion pass is run after global common -subexpression elimination. This pass will attempt to move stores out of loops. -When used in conjunction with @option{-fgcse-lm}, loops containing a load/store sequence -can be changed to a load before the loop and a store after the loop. +When @option{-fgcse-sm} is enabled, a store motion pass is run after +global common subexpression elimination. This pass will attempt to move +stores out of loops. When used in conjunction with @option{-fgcse-lm}, +loops containing a load/store sequence can be changed to a load before +the loop and a store after the loop. + +Enabled by default when gcse is enabled. + +@item -fgcse-las +@opindex fgcse-las +When @option{-fgcse-las} is enabled, the global common subexpression +elimination pass eliminates redundant loads that come after stores to the +same memory location (both partial and full redundancies). Enabled by default when gcse is enabled. @@ -3848,6 +4082,42 @@ Allow speculative motion of more load instructions. This only makes sense when scheduling before register allocation, i.e.@: with @option{-fschedule-insns} or at @option{-O2} or higher. +@item -fsched-stalled-insns=@var{n} +@opindex fsched-stalled-insns +Define how many insns (if any) can be moved prematurely from the queue +of stalled insns into the ready list, during the second scheduling pass. + +@item -fsched-stalled-insns-dep=@var{n} +@opindex fsched-stalled-insns-dep +Define how many insn groups (cycles) will be examined for a dependency +on a stalled insn that is candidate for premature removal from the queue +of stalled insns. Has an effect only during the second scheduling pass, +and only if @option{-fsched-stalled-insns} is used and its value is not zero. + +@item -fsched2-use-superblocks +@opindex fsched2-use-superblocks +When scheduling after register allocation, do use superblock scheduling +algorithm. Superblock scheduling allows motion across basic block boundaries +resulting on faster schedules. This option is experimental, as not all machine +descriptions used by GCC model the CPU closely enough to avoid unreliable +results from the algorithm. + +This only makes sense when scheduling after register allocation, i.e.@: with +@option{-fschedule-insns2} or at @option{-O2} or higher. + +@item -fsched2-use-traces +@opindex fsched2-use-traces +Use @option{-fsched2-use-superblocks} algorithm when scheduling after register +allocation and additionally perform code duplication in order to increase the +size of superblocks using tracer pass. See @option{-ftracer} for details on +trace formation. + +This mode should produce faster but significantly longer programs. Also +without @code{-fbranch-probabilities} the traces constructed may not match the +reality and hurt the performance. This only makes +sense when scheduling after register allocation, i.e.@: with +@option{-fschedule-insns2} or at @option{-O2} or higher. + @item -fcaller-saves @opindex fcaller-saves Enable values to be allocated in registers that will be clobbered by @@ -3881,11 +4151,10 @@ These two options are intended to be removed someday, once they have helped determine the efficacy of various approaches to improving loop optimizations. -Please let us (@w{@email{gcc@@gcc.gnu.org}} and @w{@email{fortran@@gnu.org}}) -know how use of these options affects -the performance of your production code. -We're very interested in code that runs @emph{slower} -when these options are @emph{enabled}. +Please contact @w{@email{gcc@@gcc.gnu.org}}, and describe how use of +these options affects the performance of your production code. +Examples of code that runs @emph{slower} when these options are +@emph{enabled} are very valuable. @item -fno-peephole @itemx -fno-peephole2 @@ -3899,12 +4168,11 @@ other, a few use both. @option{-fpeephole} is enabled by default. @option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -fbranch-probabilities @item -fno-guess-branch-probability @opindex fno-guess-branch-probability Do not guess branch probabilities using a randomized model. -Sometimes gcc will opt to use a randomized model to guess branch +Sometimes GCC will opt to use a randomized model to guess branch probabilities, when none are available from either profiling feedback (@option{-fprofile-arcs}) or @samp{__builtin_expect}. This means that different runs of the compiler on the same program may produce different @@ -3952,7 +4220,7 @@ example, an @code{unsigned int} can alias an @code{int}, but not a type. Pay special attention to code like this: -@example +@smallexample union a_union @{ int i; double d; @@ -3963,13 +4231,13 @@ int f() @{ t.d = 3.0; return t.i; @} -@end example +@end smallexample The practice of reading from a different union member than the one most recently written to (called ``type-punning'') is common. Even with @option{-fstrict-aliasing}, type-punning is allowed, provided the memory is accessed through the union type. So, the code above will work as expected. However, this code might not: -@example +@smallexample int f() @{ a_union t; int* ip; @@ -3977,7 +4245,7 @@ int f() @{ ip = &t.i; return *ip; @} -@end example +@end smallexample Every language that wishes to perform language-specific alias analysis should define a function that computes, given an @code{tree} @@ -4063,6 +4331,15 @@ will most benefit processors with lots of registers. It can, however, make debugging impossible, since variables will no longer stay in a ``home register''. +@item -fweb +@opindex fweb +Constructs webs as commonly used for register allocation purposes and assign +each web individual pseudo register. This allows the register allocation pass +to operate on pseudos directly, but also strengthens several other optimization +passes, such as CSE, loop optimizer and trivial dead code remover. It can, +however, make debugging impossible, since variables will no longer stay in a +``home register''. + Enabled at levels @option{-O3}. @item -fno-cprop-registers @@ -4073,6 +4350,24 @@ and occasionally eliminate the copy. Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item -fprofile-generate +@opindex fprofile-generate + +Enable options usually used for instrumenting application to produce +profile useful for later recompilation with profile feedback based +optimization. You must use @code{-fprofile-generate} both when +compiling and when linking your program. + +The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}. + +@item -fprofile-use +@opindex fprofile-use +Enable profile feedback directed optimizations, and optimizations +generally profitable only with profile feedback available. + +The following options are enabled: @code{-fbranch-probabilities}, +@code{-fvpt}, @code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}. + @end table The following options control compiler behavior regarding floating @@ -4098,8 +4393,8 @@ them to store all pertinent intermediate computations into variables. @item -ffast-math @opindex ffast-math Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @* -@option{-fno-trapping-math}, @option{-ffinite-math-only} and @* -@option{-fno-signaling-nans}. +@option{-fno-trapping-math}, @option{-ffinite-math-only}, +@option{-fno-rounding-math} and @option{-fno-signaling-nans}. This option causes the preprocessor macro @code{__FAST_MATH__} to be defined. @@ -4163,6 +4458,26 @@ math functions. The default is @option{-ftrapping-math}. +@item -frounding-math +@opindex frounding-math +Disable transformations and optimizations that assume default floating +point rounding behavior. This is round-to-zero for all floating point +to integer conversions, and round-to-nearest for all other arithmetic +truncations. This option should be specified for programs that change +the FP rounding mode dynamically, or that may be executed with a +non-default rounding mode. This option disables constant folding of +floating point expressions at compile-time (which may be affected by +rounding mode) and arithmetic transformations that are unsafe in the +presence of sign-dependent rounding modes. + +The default is @option{-fno-rounding-math}. + +This option is experimental and does not currently guarantee to +disable all GCC optimizations that are affected by rounding mode. +Future versions of GCC may provide finer control of this setting +using C99's @code{FENV_ACCESS} pragma. This command line option +will be used to specify the default state for @code{FENV_ACCESS}. + @item -fsignaling-nans @opindex fsignaling-nans Compile code assuming that IEEE signaling NaNs may generate user-visible @@ -4199,18 +4514,37 @@ After running a program compiled with @option{-fprofile-arcs} @option{-fbranch-probabilities}, to improve optimizations based on the number of times each branch was taken. When the program compiled with @option{-fprofile-arcs} exits it saves arc execution -counts to a file called @file{@var{sourcename}.da} for each source +counts to a file called @file{@var{sourcename}.gcda} for each source file The information in this data file is very dependent on the structure of the generated code, so you must use the same source code and the same optimization options for both compilations. -With @option{-fbranch-probabilities}, GCC puts a +With @option{-fbranch-probabilities}, GCC puts a @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}. These can be used to improve optimization. Currently, they are only used in one place: in @file{reorg.c}, instead of guessing which path a branch is mostly to take, the @samp{REG_BR_PROB} values are used to exactly determine which path is taken more often. +@item -fprofile-values +@opindex fprofile-values +If combined with @option{-fprofile-arcs}, it adds code so that some +data about values of expressions in the program is gathered. + +With @option{-fbranch-probabilities}, it reads back the data gathered +from profiling values of expressions and adds @samp{REG_VALUE_PROFILE} +notes to instructions for their later usage in optimizations. + +@item -fvpt +@opindex fvpt +If combined with @option{-fprofile-arcs}, it instructs the compiler to add +a code to gather information about values of expressions. + +With @option{-fbranch-probabilities}, it reads back the data gathered +and actually performs the optimizations based on them. +Currently the optimizations include specialization of division operation +using the knowledge about the value of the denominator. + @item -fnew-ra @opindex fnew-ra Use a graph coloring register allocator. Currently this option is meant @@ -4223,19 +4557,63 @@ Perform tail duplication to enlarge superblock size. This transformation simplifies the control flow of the function allowing other optimizations to do better job. +@item -funit-at-a-time +@opindex funit-at-a-time +Parse the whole compilation unit before starting to produce code. +This allows some extra optimizations to take place but consumes more +memory. + @item -funroll-loops @opindex funroll-loops -Unroll loops whose number of iterations can be determined at compile -time or upon entry to the loop. @option{-funroll-loops} implies both -@option{-fstrength-reduce} and @option{-frerun-cse-after-loop}. This -option makes code larger, and may or may not make it run faster. +Unroll loops whose number of iterations can be determined at compile time or +upon entry to the loop. @option{-funroll-loops} implies +@option{-frerun-cse-after-loop}. It also turns on complete loop peeling +(i.e. complete removal of loops with small constant number of iterations). +This option makes code larger, and may or may not make it run faster. @item -funroll-all-loops @opindex funroll-all-loops Unroll all loops, even if their number of iterations is uncertain when the loop is entered. This usually makes programs run more slowly. @option{-funroll-all-loops} implies the same options as -@option{-funroll-loops}, +@option{-funroll-loops}. + +@item -fpeel-loops +@opindex fpeel-loops +Peels the loops for that there is enough information that they do not +roll much (from profile feedback). It also turns on complete loop peeling +(i.e. complete removal of loops with small constant number of iterations). + +@item -funswitch-loops +@opindex funswitch-loops +Move branches with loop invariant conditions out of the loop, with duplicates +of the loop on both branches (modified according to result of the condition). + +@item -fold-unroll-loops +@opindex fold-unroll-loops +Unroll loops whose number of iterations can be determined at compile +time or upon entry to the loop, using the old loop unroller whose loop +recognition is based on notes from frontend. @option{-fold-unroll-loops} implies +both @option{-fstrength-reduce} and @option{-frerun-cse-after-loop}. This +option makes code larger, and may or may not make it run faster. + +@item -fold-unroll-all-loops +@opindex fold-unroll-all-loops +Unroll all loops, even if their number of iterations is uncertain when +the loop is entered. This is done using the old loop unroller whose loop +recognition is based on notes from frontend. This usually makes programs run more slowly. +@option{-fold-unroll-all-loops} implies the same options as +@option{-fold-unroll-loops}. + +@item -funswitch-loops +@opindex funswitch-loops +Move branches with loop invariant conditions out of the loop, with duplicates +of the loop on both branches (modified according to result of the condition). + +@item -funswitch-loops +@opindex funswitch-loops +Move branches with loop invariant conditions out of the loop, with duplicates +of the loop on both branches (modified according to result of the condition). @item -fprefetch-loop-arrays @opindex fprefetch-loop-arrays @@ -4266,23 +4644,18 @@ You will not be able to use @code{gprof} on all systems if you specify this option and you may have problems with debugging if you specify both this option and @option{-g}. -@item -fssa -@opindex fssa -Perform optimizations in static single assignment form. Each function's -flow graph is translated into SSA form, optimizations are performed, and -the flow graph is translated back from SSA form. Users should not -specify this option, since it is not yet ready for production use. - -@item -fssa-ccp -@opindex fssa-ccp -Perform Sparse Conditional Constant Propagation in SSA form. Requires -@option{-fssa}. Like @option{-fssa}, this is an experimental feature. - -@item -fssa-dce -@opindex fssa-dce -Perform aggressive dead-code elimination in SSA form. Requires @option{-fssa}. -Like @option{-fssa}, this is an experimental feature. +@item -fbranch-target-load-optimize +@opindex fbranch-target-load-optimize +Perform branch target register load optimization before prologue / epilogue +threading. +The use of target registers can typically be exposed only during reload, +thus hoisting loads out of loops and doing inter-block scheduling needs +a separate optimization pass. +@item -fbranch-target-load-optimize2 +@opindex fbranch-target-load-optimize2 +Perform branch target register load optimization after prologue / epilogue +threading. @item --param @var{name}=@var{value} @opindex param @@ -4292,6 +4665,10 @@ that contain more that a certain number of instructions. You can control some of these constants on the command-line using the @option{--param} option. +The names of specific parameters, and the meaning of the values, are +tied to the internals of the compiler, and are subject to change +without notice in future releases. + In each case, the @var{value} is an integer. The allowable choices for @var{name} are given in the following table: @@ -4336,11 +4713,11 @@ needlessly consume memory and resources. @item max-inline-insns-single Several parameters control the tree inliner used in gcc. -This number sets the maximum number of instructions (counted in gcc's -internal representation) in a single function that the tree inliner +This number sets the maximum number of instructions (counted in GCC's +internal representation) in a single function that the tree inliner will consider for inlining. This only affects functions declared inline and methods implemented in a class declaration (C++). -The default value is 300. +The default value is 500. @item max-inline-insns-auto When you use @option{-finline-functions} (included in @option{-O3}), @@ -4348,45 +4725,65 @@ a lot of functions that would otherwise not be considered for inlining by the compiler will be investigated. To those functions, a different (more restrictive) limit compared to functions declared inline can be applied. -The default value is 300. - -@item max-inline-insns -The tree inliner does decrease the allowable size for single functions -to be inlined after we already inlined the number of instructions -given here by repeated inlining. This number should be a factor of -two or more larger than the single function limit. -Higher numbers result in better runtime performance, but incur higher -compile-time resource (CPU time, memory) requirements and result in -larger binaries. Very high values are not advisable, as too large -binaries may adversely affect runtime performance. -The default value is 600. - -@item max-inline-slope -After exceeding the maximum number of inlined instructions by repeated -inlining, a linear function is used to decrease the allowable size -for single functions. The slope of that function is the negative -reciprocal of the number specified here. -The default value is 32. - -@item min-inline-insns -The repeated inlining is throttled more and more by the linear function -after exceeding the limit. To avoid too much throttling, a minimum for -this function is specified here to allow repeated inlining for very small -functions even when a lot of repeated inlining already has been done. -The default value is 130. +The default value is 100. + +@item large-function-insns +The limit specifying really large functions. For functions greater than this +limit inlining is constrained by @option{--param large-function-growth}. +This parameter is useful primarily to avoid extreme compilation time caused by non-linear +algorithms used by the backend. +This parameter is ignored when @option{-funit-at-a-time} is not used. +The default value is 3000. + +@item large-function-growth +Specifies maximal growth of large function caused by inlining in percents. +This parameter is ignored when @option{-funit-at-a-time} is not used. +The default value is 200. + +@item inline-unit-growth +Specifies maximal overall growth of the compilation unit caused by inlining. +This parameter is ignored when @option{-funit-at-a-time} is not used. +The default value is 150. @item max-inline-insns-rtl For languages that use the RTL inliner (this happens at a later stage -than tree inlining), you can set the maximum allowable size (counted +than tree inlining), you can set the maximum allowable size (counted in RTL instructions) for the RTL inliner with this parameter. The default value is 600. - @item max-unrolled-insns The maximum number of instructions that a loop should have if that loop is unrolled, and if the loop is unrolled, it determines how many times the loop code is unrolled. +@item max-average-unrolled-insns +The maximum number of instructions biased by probabilities of their execution +that a loop should have if that loop is unrolled, and if the loop is unrolled, +it determines how many times the loop code is unrolled. + +@item max-unroll-times +The maximum number of unrollings of a single loop. + +@item max-peeled-insns +The maximum number of instructions that a loop should have if that loop +is peeled, and if the loop is peeled, it determines how many times +the loop code is peeled. + +@item max-peel-times +The maximum number of peelings of a single loop. + +@item max-completely-peeled-insns +The maximum number of insns of a completely peeled loop. + +@item max-completely-peel-times +The maximum number of iterations of a loop to be suitable for complete peeling. + +@item max-unswitch-insns +The maximum number of insns of an unswitched loop. + +@item max-unswitch-level +The maximum number of branches unswitched in a single loop. + @item hot-bb-count-fraction Select fraction of the maximal count of repetitions of basic block in program given basic block needs to have to be considered hot. @@ -4428,6 +4825,10 @@ compilation for profile feedback and one for compilation without. The value for compilation with profile feedback needs to be more conservative (higher) in order to make tracer effective. +@item max-cse-path-length + +Maximum number of basic blocks on path that cse considers. + @item ggc-min-expand GCC uses a garbage collector to manage its own memory allocation. This @@ -4462,6 +4863,29 @@ parameter very large effectively disables garbage collection. Setting this parameter and @option{ggc-min-expand} to zero causes a full collection to occur at every opportunity. +@item max-reload-search-insns +The maximum number of instruction reload should look backward for equivalent +register. Increasing values mean more aggressive optimization, making the +compile time increase with probably slightly better performance. The default +value is 100. + +@item max-cselib-memory-location +The maximum number of memory locations cselib should take into acount. +Increasing values mean more aggressive optimization, making the compile time +increase with probably slightly better performance. The default value is 500. + +@item reorder-blocks-duplicate +@itemx reorder-blocks-duplicate-feedback + +Used by basic block reordering pass to decide whether to use unconditional +branch or duplicate the code on its destination. Code is duplicated when its +estimated size is smaller than this value multiplied by the estimated size of +unconditional jump in the hot spots of the program. + +The @option{reorder-block-duplicate-feedback} is used only when profile +feedback is available and may be set to higher values than +@option{reorder-block-duplicate} since information about the hot spots is more +accurate. @end table @end table @@ -4478,6 +4902,7 @@ Some of these options make sense only together with @option{-E} because they cause the preprocessor output to be unsuitable for actual compilation. +@table @gcctabopt @opindex Wp You can use @option{-Wp,@var{option}} to bypass the compiler driver and pass @var{option} directly through to the preprocessor. If @@ -4489,6 +4914,16 @@ interface is undocumented and subject to change, so whenever possible you should avoid using @option{-Wp} and let the driver handle the options instead. +@item -Xpreprocessor @var{option} +@opindex preprocessor +Pass @var{option} as an option to the preprocessor. You can use this to +supply system-specific preprocessor options which GCC does not know how to +recognize. + +If you want to pass an option that takes an argument, you must use +@option{-Xpreprocessor} twice, once for the option and once for the argument. +@end table + @include cppopts.texi @node Assembler Options @@ -4502,6 +4937,16 @@ You can pass options to the assembler. @opindex Wa Pass @var{option} as an option to the assembler. If @var{option} contains commas, it is split into multiple options at the commas. + +@item -Xassembler @var{option} +@opindex Xassembler +Pass @var{option} as an option to the assembler. You can use this to +supply system-specific assembler options which GCC does not know how to +recognize. + +If you want to pass an option that takes an argument, you must use +@option{-Xassembler} twice, once for the option and once for the argument. + @end table @node Link Options @@ -4615,6 +5060,13 @@ library subroutines. (For example, @samp{__main}, used to ensure C++ constructors will be called; @pxref{Collect2,,@code{collect2}, gccint, GNU Compiler Collection (GCC) Internals}.) +@item -pie +@opindex pie +Produce a position independent executable on targets which support it. +For predictable results, you must also specify the same set of options +that were used to generate code (@option{-fpie}, @option{-fPIE}, +or model suboptions) when you specify this option. + @item -s @opindex s Remove all symbol table and relocation information from the executable. @@ -4659,14 +5111,14 @@ this is the right thing to do. If, instead, you use the GCC driver to create shared libraries, you may find that they will not always be linked with the shared @file{libgcc}. -If GCC finds, at its configuration time, that you have a GNU linker that -does not support option @option{--eh-frame-hdr}, it will link the shared -version of @file{libgcc} into shared libraries by default. Otherwise, -it will take advantage of the linker and optimize away the linking with -the shared version of @file{libgcc}, linking with the static version of -libgcc by default. This allows exceptions to propagate through such -shared libraries, without incurring relocation costs at library load -time. +If GCC finds, at its configuration time, that you have a non-GNU linker +or a GNU linker that does not support option @option{--eh-frame-hdr}, +it will link the shared version of @file{libgcc} into shared libraries +by default. Otherwise, it will take advantage of the linker and optimize +away the linking with the shared version of @file{libgcc}, linking with +the static version of libgcc by default. This allows exceptions to +propagate through such shared libraries, without incurring relocation +costs at library load time. However, if a library or main executable is supposed to throw or catch exceptions, you must link it using the G++ or GCJ driver, as appropriate @@ -4777,7 +5229,7 @@ without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}). For each subprogram to be run, the compiler driver first tries the @option{-B} prefix, if any. If that name is not found, or if @option{-B} was not specified, the driver tries two standard prefixes, which are -@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of +@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of those results in a file name that is found, the unmodified program name is searched for using the directories specified in your @env{PATH} environment variable. @@ -5022,6 +5474,15 @@ of a temporary file, just like @samp{%u}. This temporary file is not meant for communication between processes, but rather as a junk disposal mechanism. +@item %|@var{suffix} +@itemx %m@var{suffix} +Like @samp{%g}, except if @option{-pipe} is in effect. In that case +@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at +all. These are the two most common ways to instruct a program that it +should read from standard input or write to standard output. If you +need something more elaborate you can use an @samp{%@{pipe:@code{X}@}} +construct: see for example @file{f/lang-specs.h}. + @item %.@var{SUFFIX} Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args when it is subsequently output with @samp{%*}. @var{SUFFIX} is @@ -5061,7 +5522,10 @@ predefined macro, except for macros that start with @samp{__} or with C@. @item %I -Substitute a @option{-iprefix} option made from @env{GCC_EXEC_PREFIX}. +Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}), +@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}), and +@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options) +as necessary. @item %s Current argument is the name of a library or startup file of some sort. @@ -5072,9 +5536,6 @@ the full name found. Print @var{str} as an error message. @var{str} is terminated by a newline. Use this when inconsistent options are detected. -@item %| -Output @samp{-} if the input for the current command is coming from a pipe. - @item %(@var{name}) Substitute the contents of spec string @var{name} at this point. @@ -5094,18 +5555,6 @@ Output the accumulated assembler options specified by @option{-Wa}. @item %Z Output the accumulated preprocessor options specified by @option{-Wp}. -@item %v1 -Substitute the major version number of GCC@. -(For version 2.9.5, this is 2.) - -@item %v2 -Substitute the minor version number of GCC@. -(For version 2.9.5, this is 9.) - -@item %v3 -Substitute the patch level number of GCC@. -(For version 2.9.5, this is 5.) - @item %a Process the @code{asm} spec. This is used to compute the switches to be passed to the assembler. @@ -5171,6 +5620,12 @@ Substitute the variable part of a matched option. See below. Note that each comma in the substituted string is replaced by a single space. +@item %<@code{S} +Remove all occurrences of @code{-S} from the command line. Note---this +command is position dependent. @samp{%} commands in the spec string +before this one will see @code{-S}, @samp{%} commands in the spec string +after this one will not. + @item %:@var{function}(@var{args}) Call the named function @var{function}, passing it @var{args}. @var{args} is first processed as a nested spec string, then split @@ -5199,12 +5654,12 @@ returns the pathname. If it does not exist, it returns the second argument. This way, @code{if-exists-else} can be used to select one file or another, based on the existence of the first. Here is a small example of its usage: -@smallexample +@smallexample *startfile: crt0%O%s %:if-exists(crti%O%s) \ %:if-exists-else(crtbeginT%O%s crtbegin%O%s) @end smallexample -@end table +@end table @item %@{@code{S}@} Substitutes the @code{-S} switch, if that switch was given to GCC@. @@ -5226,51 +5681,40 @@ GCC considers @option{-o foo} as being one switch whose names starts with @samp{o}. %@{o*@} would substitute this text, including the space. Thus two arguments would be generated. -@item %@{^@code{S}*@} -Like %@{@code{S}*@}, but don't put a blank between a switch and its -argument. Thus %@{^o*@} would only generate one argument, not two. - @item %@{@code{S}*&@code{T}*@} Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options (the order of @code{S} and @code{T} in the spec is not significant). There can be any number of ampersand-separated variables; for each the wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}. -@item %@{<@code{S}@} -Remove all occurrences of @code{-S} from the command line. Note---this -command is position dependent. @samp{%} commands in the spec string -before this option will see @code{-S}, @samp{%} commands in the spec -string after this option will not. - -@item %@{@code{S}*:@code{X}@} -Substitutes @code{X} if one or more switches whose names start with -@code{-S} are specified to GCC@. Note that the tail part of the -@code{-S} option (i.e.@: the part matched by the @samp{*}) will be substituted -for each occurrence of @samp{%*} within @code{X}. - @item %@{@code{S}:@code{X}@} -Substitutes @code{X}, but only if the @samp{-S} switch was given to GCC@. +Substitutes @code{X}, if the @samp{-S} switch was given to GCC@. @item %@{!@code{S}:@code{X}@} -Substitutes @code{X}, but only if the @samp{-S} switch was @emph{not} given to GCC@. - -@item %@{|@code{S}:@code{X}@} -Like %@{@code{S}:@code{X}@}, but if no @code{S} switch, substitute @samp{-}. +Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@. -@item %@{|!@code{S}:@code{X}@} -Like %@{!@code{S}:@code{X}@}, but if there is an @code{S} switch, substitute @samp{-}. +@item %@{@code{S}*:@code{X}@} +Substitutes @code{X} if one or more switches whose names start with +@code{-S} are specified to GCC@. Normally @code{X} is substituted only +once, no matter how many such switches appeared. However, if @code{%*} +appears somewhere in @code{X}, then @code{X} will be substituted once +for each matching switch, with the @code{%*} replaced by the part of +that switch that matched the @code{*}. @item %@{.@code{S}:@code{X}@} -Substitutes @code{X}, but only if processing a file with suffix @code{S}. +Substitutes @code{X}, if processing a file with suffix @code{S}. @item %@{!.@code{S}:@code{X}@} -Substitutes @code{X}, but only if @emph{not} processing a file with suffix @code{S}. +Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}. @item %@{@code{S}|@code{P}:@code{X}@} -Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@. This may be -combined with @samp{!} and @samp{.} sequences as well, although they -have a stronger binding than the @samp{|}. For example a spec string -like this: +Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@. +This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well, +although they have a stronger binding than the @samp{|}. If @code{%*} +appears in @code{X}, all of the alternatives must be starred, and only +the first matching alternative is substituted. + +For example, a spec string like this: @smallexample %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@} @@ -5286,23 +5730,33 @@ jim.d -bar -boggle -d jim.d -bar -baz -boggle @end smallexample +@item %@{S:X; T:Y; :D@} + +If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was +given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can +be as many clauses as you need. This may be combined with @code{.}, +@code{!}, @code{|}, and @code{*} as needed. + + @end table -The conditional text @code{X} in a %@{@code{S}:@code{X}@} or -%@{!@code{S}:@code{X}@} construct may contain other nested @samp{%} constructs -or spaces, or even newlines. They are processed as usual, as described -above. +The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar +construct may contain other nested @samp{%} constructs or spaces, or +even newlines. They are processed as usual, as described above. +Trailing white space in @code{X} is ignored. White space may also +appear anywhere on the left side of the colon in these constructs, +except between @code{.} or @code{*} and the corresponding word. -The @option{-O}, @option{-f}, @option{-m}, and @option{-W} -switches are handled specifically in these -constructs. If another value of @option{-O} or the negated form of a @option{-f}, @option{-m}, or -@option{-W} switch is found later in the command line, the earlier switch -value is ignored, except with @{@code{S}*@} where @code{S} is just one -letter, which passes all matching options. +The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are +handled specifically in these constructs. If another value of +@option{-O} or the negated form of a @option{-f}, @option{-m}, or +@option{-W} switch is found later in the command line, the earlier +switch value is ignored, except with @{@code{S}*@} where @code{S} is +just one letter, which passes all matching options. -The character @samp{|} at the beginning of the predicate text is used to indicate -that a command should be piped to the following command, but only if @option{-pipe} -is specified. +The character @samp{|} at the beginning of the predicate text is used to +indicate that a command should be piped to the following command, but +only if @option{-pipe} is specified. It is built into GCC which switches take arguments and which do not. (You might think it would be useful to generalize this to allow each @@ -5387,13 +5841,10 @@ that macro, which enables you to change the defaults. * VAX Options:: * SPARC Options:: * ARM Options:: -* MN10200 Options:: * MN10300 Options:: * M32R/D Options:: -* M88K Options:: * RS/6000 and PowerPC Options:: * Darwin Options:: -* RT Options:: * MIPS Options:: * i386 and x86-64 Options:: * HPPA Options:: @@ -5508,10 +5959,6 @@ This results in code which can run relatively efficiently on either a 68020/68881 or a 68030 or a 68040. The generated code does use the 68881 instructions that are emulated on the 68060. -@item -mfpa -@opindex mfpa -Generate output containing Sun FPA instructions for floating point. - @item -msoft-float @opindex msoft-float Generate output containing library calls for floating point. @@ -5590,6 +6037,30 @@ not presently supported with @option{-mpcrel}, though this could be supported fo Do not (do) assume that unaligned memory references will be handled by the system. +@item -msep-data +Generate code that allows the data segment to be located in a different +area of memory from the text segment. This allows for execute in place in +an environment without virtual memory management. This option implies -fPIC. + +@item -mno-sep-data +Generate code that assumes that the data segment follows the text segment. +This is the default. + +@item -mid-shared-library +Generate code that supports shared libraries via the library ID method. +This allows for execute in place and shared libraries in an environment +without virtual memory management. This option implies -fPIC. + +@item -mno-id-shared-library +Generate code that doesn't assume ID based shared libraries are being used. +This is the default. + +@item -mshared-library-id=n +Specified the identification number of the ID based shared library being +compiled. Specifying a value of 0 will generate more compact code, specifying +other values will force the allocation of that number to the current +library but is no more space or time efficient than omitting this option. + @end table @node M68hc1x Options @@ -5620,7 +6091,7 @@ when the compiler is configured for 68HC12-based systems. @itemx -m68hcs12 @opindex m68S12 @opindex m68hcs12 -Generate output for a 68HCS12. +Generate output for a 68HCS12. @item -mauto-incdec @opindex mauto-incdec @@ -5681,7 +6152,7 @@ Output code for g-format floating point numbers instead of d-format. @subsection SPARC Options @cindex SPARC options -These @samp{-m} switches are supported on the SPARC: +These @samp{-m} options are supported on the SPARC: @table @gcctabopt @item -mno-app-regs @@ -5732,7 +6203,7 @@ Generate output containing library calls for quad-word (long double) floating point instructions. The functions called are those specified in the SPARC ABI@. This is the default. -As of this writing, there are no sparc implementations that have hardware +As of this writing, there are no SPARC implementations that have hardware support for the quad-word floating point instructions. They all invoke a trap handler for one of these instructions, and then the trap handler emulates the effect of the instruction. Because of the trap handler overhead, @@ -5753,6 +6224,8 @@ The local registers and the input registers (0--5) are still treated as With @option{-mno-flat} (the default), the compiler emits save/restore instructions (except for leaf functions) and is the normal mode of operation. +These options are deprecated and will be deleted in a future GCC release. + @item -mno-unaligned-doubles @itemx -munaligned-doubles @opindex mno-unaligned-doubles @@ -5784,7 +6257,7 @@ the rules of the ABI@. @option{-mimpure-text}, used in addition to @option{-shared}, tells the compiler to not pass @option{-z text} to the linker when linking a shared object. Using this option, you can link position-dependent -code into a shared object. +code into a shared object. @option{-mimpure-text} suppresses the ``relocations remain against allocatable but non-writable sections'' linker error message. @@ -5800,35 +6273,18 @@ This option is only available on SunOS and Solaris. @opindex mv8 @opindex msparclite These two options select variations on the SPARC architecture. - -By default (unless specifically configured for the Fujitsu SPARClite), -GCC generates code for the v7 variant of the SPARC architecture. - -@option{-mv8} will give you SPARC v8 code. The only difference from v7 -code is that the compiler emits the integer multiply and integer -divide instructions which exist in SPARC v8 but not in SPARC v7. - -@option{-msparclite} will give you SPARClite code. This adds the integer -multiply, integer divide step and scan (@code{ffs}) instructions which -exist in SPARClite but not in SPARC v7. - These options are deprecated and will be deleted in a future GCC release. They have been replaced with @option{-mcpu=xxx}. @item -mcypress @itemx -msupersparc +@itemx -mf930 +@itemx -mf934 @opindex mcypress @opindex msupersparc -These two options select the processor for which the code is optimized. - -With @option{-mcypress} (the default), the compiler optimizes code for the -Cypress CY7C602 chip, as used in the SPARCStation/SPARCServer 3xx series. -This is also appropriate for the older SPARCStation 1, 2, IPX etc. - -With @option{-msupersparc} the compiler optimizes code for the SuperSPARC cpu, as -used in the SPARCStation 10, 1000 and 2000 series. This flag also enables use -of the full SPARC v8 instruction set. - +@opindex -mf930 +@opindex -mf934 +These four options select the processor for which the code is optimized. These options are deprecated and will be deleted in a future GCC release. They have been replaced with @option{-mcpu=xxx}. @@ -5837,7 +6293,7 @@ They have been replaced with @option{-mcpu=xxx}. Set the instruction set, register set, and instruction scheduling parameters for machine type @var{cpu_type}. Supported values for @var{cpu_type} are @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite}, -@samp{hypersparc}, @samp{sparclite86x}, @samp{f930}, @samp{f934}, +@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x}, @samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc}, and @samp{ultrasparc3}. @@ -5856,6 +6312,41 @@ implementations. v9: ultrasparc, ultrasparc3 @end smallexample +By default (unless configured otherwise), GCC generates code for the V7 +variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler +additionally optimizes it for the Cypress CY7C602 chip, as used in the +SPARCStation/SPARCServer 3xx series. This is also appropriate for the older +SPARCStation 1, 2, IPX etc. + +With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC +architecture. The only difference from V7 code is that the compiler emits +the integer multiply and integer divide instructions which exist in SPARC-V8 +but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally +optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and +2000 series. + +With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of +the SPARC architecture. This adds the integer multiply, integer divide step +and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7. +With @option{-mcpu=f930}, the compiler additionally optimizes it for the +Fujitsu MB86930 chip, which is the original SPARClite, with no FPU. With +@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu +MB86934 chip, which is the more recent SPARClite with FPU. + +With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of +the SPARC architecture. This adds the integer multiply, multiply/accumulate, +integer divide step and scan (@code{ffs}) instructions which exist in SPARClet +but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally +optimizes it for the TEMIC SPARClet chip. + +With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC +architecture. This adds 64-bit integer and floating-point move instructions, +3 additional floating-point condition code registers and conditional move +instructions. With @option{-mcpu=ultrasparc}, the compiler additionally +optimizes it for the Sun UltraSPARC I/II chips. With +@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the +Sun UltraSPARC III chip. + @item -mtune=@var{cpu_type} @opindex mtune Set the instruction scheduling parameters for machine type @@ -5869,36 +6360,25 @@ that select a particular cpu implementation. Those are @samp{cypress}, @samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc}, and @samp{ultrasparc3}. +@item -mv8plus +@itemx -mno-v8plus +@opindex mv8plus +@opindex mno-v8plus +With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI. The +difference from the V8 ABI is that the global and out registers are +considered 64-bit wide. This is enabled by default on Solaris in 32-bit +mode for all SPARC-V9 processors. + +@item -mvis +@itemx -mno-vis +@opindex mvis +@opindex mno-vis +With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC +Visual Instruction Set extensions. The default is @option{-mno-vis}. @end table -These @samp{-m} switches are supported in addition to the above -on the SPARCLET processor. - -@table @gcctabopt -@item -mlittle-endian -@opindex mlittle-endian -Generate code for a processor running in little-endian mode. - -@item -mlive-g0 -@opindex mlive-g0 -Treat register @code{%g0} as a normal register. -GCC will continue to clobber it as necessary but will not assume -it always reads as 0. - -@item -mbroken-saverestore -@opindex mbroken-saverestore -Generate code that does not use non-trivial forms of the @code{save} and -@code{restore} instructions. Early versions of the SPARCLET processor do -not correctly handle @code{save} and @code{restore} instructions used with -arguments. They correctly handle them used without arguments. A @code{save} -instruction used without arguments increments the current window pointer -but does not allocate a new stack frame. It is assumed that the window -overflow trap handler will properly handle this case as will interrupt -handlers. -@end table - -These @samp{-m} switches are supported in addition to the above -on SPARC V9 processors in 64-bit environments. +These @samp{-m} options are supported in addition to the above +on SPARC-V9 processors in 64-bit environments: @table @gcctabopt @item -mlittle-endian @@ -5917,31 +6397,31 @@ to 64 bits. @item -mcmodel=medlow @opindex mcmodel=medlow -Generate code for the Medium/Low code model: the program must be linked -in the low 32 bits of the address space. Pointers are 64 bits. -Programs can be statically or dynamically linked. +Generate code for the Medium/Low code model: 64-bit addresses, programs +must be linked in the low 32 bits of memory. Programs can be statically +or dynamically linked. @item -mcmodel=medmid @opindex mcmodel=medmid -Generate code for the Medium/Middle code model: the program must be linked -in the low 44 bits of the address space, the text segment must be less than -2G bytes, and data segment must be within 2G of the text segment. -Pointers are 64 bits. +Generate code for the Medium/Middle code model: 64-bit addresses, programs +must be linked in the low 44 bits of memory, the text and data segments must +be less than 2GB in size and the data segment must be located within 2GB of +the text segment. @item -mcmodel=medany @opindex mcmodel=medany -Generate code for the Medium/Anywhere code model: the program may be linked -anywhere in the address space, the text segment must be less than -2G bytes, and data segment must be within 2G of the text segment. -Pointers are 64 bits. +Generate code for the Medium/Anywhere code model: 64-bit addresses, programs +may be linked anywhere in memory, the text and data segments must be less +than 2GB in size and the data segment must be located within 2GB of the +text segment. @item -mcmodel=embmedany @opindex mcmodel=embmedany Generate code for the Medium/Anywhere code model for embedded systems: -assume a 32-bit text and a 32-bit data segment, both starting anywhere -(determined at link time). Register %g4 points to the base of the -data segment. Pointers are still 64 bits. -Programs are statically linked, PIC is not supported. +64-bit addresses, the text and data segments must be less than 2GB in +size, both starting anywhere in memory (determined at link time). The +global register %g4 points to the base of the data segment. Programs +are statically linked and PIC is not supported. @item -mstack-bias @itemx -mno-stack-bias @@ -5949,10 +6429,28 @@ Programs are statically linked, PIC is not supported. @opindex mno-stack-bias With @option{-mstack-bias}, GCC assumes that the stack pointer, and frame pointer if present, are offset by @minus{}2047 which must be added back -when making stack frame references. +when making stack frame references. This is the default in 64-bit mode. Otherwise, assume no such offset is present. @end table +These switches are supported in addition to the above on Solaris: + +@table @gcctabopt +@item -threads +@opindex threads +Add support for multithreading using the Solaris threads library. This +option sets flags for both the preprocessor and linker. This option does +not affect the thread safety of object code produced by the compiler or +that of libraries supplied with it. + +@item -pthreads +@opindex pthreads +Add support for multithreading using the POSIX threads library. This +option sets flags for both the preprocessor and linker. This option does +not affect the thread safety of object code produced by the compiler or +that of libraries supplied with it. +@end table + @node ARM Options @subsection ARM Options @cindex ARM options @@ -5977,15 +6475,19 @@ This is a synonym for @option{-mapcs-frame}. @opindex mapcs-26 Generate code for a processor running with a 26-bit program counter, and conforming to the function calling standards for the APCS 26-bit -option. This option replaces the @option{-m2} and @option{-m3} options -of previous releases of the compiler. +option. + +This option is deprecated. Future releases of the GCC will only support +generating code that runs in apcs-32 mode. @item -mapcs-32 @opindex mapcs-32 Generate code for a processor running with a 32-bit program counter, and conforming to the function calling standards for the APCS 32-bit -option. This option replaces the @option{-m6} option of previous releases -of the compiler. +option. + +This flag is deprecated. Future releases of GCC will make this flag +unconditional. @ignore @c not currently implemented @@ -6086,7 +6588,7 @@ synthesize the access as a series of byte accesses. The compiler can still use word accesses to load half-word data if it knows that the address is aligned to a word boundary. -This option is ignored when compiling for ARM architecture 4 or later, +This option has no effect when compiling for ARM architecture 4 or later, since these processors have instructions to directly access half-word objects in memory. @@ -6101,21 +6603,11 @@ Note that you cannot use this option to access unaligned word objects, since the processor will only fetch one 32-bit aligned object from memory. -The default setting for most targets is @option{-mno-alignment-traps}, since -this produces better code when there are no half-word memory -instructions available. +The default setting is @option{-malignment-traps}, since this produces +code that will also run on processors implementing ARM architecture +version 6 or later. -@item -mshort-load-bytes -@itemx -mno-short-load-words -@opindex mshort-load-bytes -@opindex mno-short-load-words -These are deprecated aliases for @option{-malignment-traps}. - -@item -mno-short-load-bytes -@itemx -mshort-load-words -@opindex mno-short-load-bytes -@opindex mshort-load-words -This are deprecated aliases for @option{-mno-alignment-traps}. +This option is deprecated and will be removed in the next release of GCC. @item -mcpu=@var{name} @opindex mcpu @@ -6129,8 +6621,10 @@ assembly code. Permissible names are: @samp{arm2}, @samp{arm250}, @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100}, @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920}, -@samp{arm920t}, @samp{arm940t}, @samp{arm9tdmi}, @samp{arm10tdmi}, -@samp{arm1020t}, @samp{xscale}. +@samp{arm920t}, @samp{arm926ejs}, @samp{arm940t}, @samp{arm9tdmi}, +@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ejs}, +@samp{arm1136js}, @samp{arm1136jfs} ,@samp{xscale}, @samp{iwmmxt}, +@samp{ep9312}. @itemx -mtune=@var{name} @opindex mtune @@ -6150,7 +6644,8 @@ name to determine what kind of instructions it can emit when generating assembly code. This option can be used in conjunction with or instead of the @option{-mcpu=} option. Permissible names are: @samp{armv2}, @samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t}, -@samp{armv5}, @samp{armv5t}, @samp{armv5te}. +@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6j}, +@samp{iwmmxt}, @samp{ep9312}. @item -mfpe=@var{number} @itemx -mfp=@var{number} @@ -6222,6 +6717,18 @@ before execution begins. Specify the register to be used for PIC addressing. The default is R10 unless stack-checking is enabled, when R9 is used. +@item -mcirrus-fix-invalid-insns +@opindex mcirrus-fix-invalid-insns +@opindex mno-cirrus-fix-invalid-insns +Insert NOPs into the instruction stream to in order to work around +problems with invalid Maverick instruction combinations. This option +is only valid if the @option{-mcpu=ep9312} option has been used to +enable generation of instructions for the Cirrus Maverick floating +point co-processor. This option is not enabled by default, since the +problem is only present in older Maverick implementations. The default +can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns} +switch. + @item -mpoke-function-name @opindex mpoke-function-name Write the name of each function into the text section, directly @@ -6278,22 +6785,6 @@ of executing a function pointer if this option is enabled. @end table -@node MN10200 Options -@subsection MN10200 Options -@cindex MN10200 options - -These @option{-m} options are defined for Matsushita MN10200 architectures: -@table @gcctabopt - -@item -mrelax -@opindex mrelax -Indicate to the linker that it should perform a relaxation optimization pass -to shorten branches, calls and absolute memory addresses. This option only -has an effect when used on the command line for the final link step. - -This option makes symbolic debugging impossible. -@end table - @node MN10300 Options @subsection MN10300 Options @cindex MN10300 options @@ -6338,9 +6829,13 @@ This option makes symbolic debugging impossible. @subsection M32R/D Options @cindex M32R/D options -These @option{-m} options are defined for Mitsubishi M32R/D architectures: +These @option{-m} options are defined for Renesas M32R/D architectures: @table @gcctabopt +@item -m32r2 +@opindex m32r2 +Generate code for the M32R/2@. + @item -m32rx @opindex m32rx Generate code for the M32R/X@. @@ -6349,8 +6844,8 @@ Generate code for the M32R/X@. @opindex m32r Generate code for the M32R@. This is the default. -@item -mcode-model=small -@opindex mcode-model=small +@item -mmodel=small +@opindex mmodel=small Assume all objects live in the lower 16MB of memory (so that their addresses can be loaded with the @code{ld24} instruction), and assume all subroutines are reachable with the @code{bl} instruction. @@ -6359,14 +6854,14 @@ This is the default. The addressability of a particular object can be set with the @code{model} attribute. -@item -mcode-model=medium -@opindex mcode-model=medium +@item -mmodel=medium +@opindex mmodel=medium Assume objects may be anywhere in the 32-bit address space (the compiler will generate @code{seth/add3} instructions to load their addresses), and assume all subroutines are reachable with the @code{bl} instruction. -@item -mcode-model=large -@opindex mcode-model=large +@item -mmodel=large +@opindex mmodel=large Assume objects may be anywhere in the 32-bit address space (the compiler will generate @code{seth/add3} instructions to load their addresses), and assume subroutines may not be reachable with the @code{bl} instruction @@ -6408,237 +6903,51 @@ Compiling with different values of @var{num} may or may not work; if it doesn't the linker will give an error message---incorrect code will not be generated. -@end table - -@node M88K Options -@subsection M88K Options -@cindex M88k options - -These @samp{-m} options are defined for Motorola 88k architectures: - -@table @gcctabopt -@item -m88000 -@opindex m88000 -Generate code that works well on both the m88100 and the -m88110. - -@item -m88100 -@opindex m88100 -Generate code that works best for the m88100, but that also -runs on the m88110. - -@item -m88110 -@opindex m88110 -Generate code that works best for the m88110, and may not run -on the m88100. - -@item -mbig-pic -@opindex mbig-pic -Obsolete option to be removed from the next revision. -Use @option{-fPIC}. - -@item -midentify-revision -@opindex midentify-revision -@cindex identifying source, compiler (88k) -Include an @code{ident} directive in the assembler output recording the -source file name, compiler name and version, timestamp, and compilation -flags used. - -@item -mno-underscores -@opindex mno-underscores -@cindex underscores, avoiding (88k) -In assembler output, emit symbol names without adding an underscore -character at the beginning of each name. The default is to use an -underscore as prefix on each name. - -@item -mocs-debug-info -@itemx -mno-ocs-debug-info -@opindex mocs-debug-info -@opindex mno-ocs-debug-info -@cindex OCS (88k) -@cindex debugging, 88k OCS -Include (or omit) additional debugging information (about registers used -in each stack frame) as specified in the 88open Object Compatibility -Standard, ``OCS''@. This extra information allows debugging of code that -has had the frame pointer eliminated. The default for SVr4 and Delta 88 -SVr3.2 is to include this information; other 88k configurations omit this -information by default. - -@item -mocs-frame-position -@opindex mocs-frame-position -@cindex register positions in frame (88k) -When emitting COFF debugging information for automatic variables and -parameters stored on the stack, use the offset from the canonical frame -address, which is the stack pointer (register 31) on entry to the -function. The SVr4 and Delta88 SVr3.2, and BCS configurations use -@option{-mocs-frame-position}; other 88k configurations have the default -@option{-mno-ocs-frame-position}. - -@item -mno-ocs-frame-position -@opindex mno-ocs-frame-position -@cindex register positions in frame (88k) -When emitting COFF debugging information for automatic variables and -parameters stored on the stack, use the offset from the frame pointer -register (register 30). When this option is in effect, the frame -pointer is not eliminated when debugging information is selected by the --g switch. - -@item -moptimize-arg-area -@opindex moptimize-arg-area -@cindex arguments in frame (88k) -Save space by reorganizing the stack frame. This option generates code -that does not agree with the 88open specifications, but uses less -memory. - -@itemx -mno-optimize-arg-area -@opindex mno-optimize-arg-area -Do not reorganize the stack frame to save space. This is the default. -The generated conforms to the specification, but uses more memory. - -@item -mshort-data-@var{num} -@opindex mshort-data -@cindex smaller data references (88k) -@cindex r0-relative references (88k) -Generate smaller data references by making them relative to @code{r0}, -which allows loading a value using a single instruction (rather than the -usual two). You control which data references are affected by -specifying @var{num} with this option. For example, if you specify -@option{-mshort-data-512}, then the data references affected are those -involving displacements of less than 512 bytes. -@option{-mshort-data-@var{num}} is not effective for @var{num} greater -than 64k. - -@item -mserialize-volatile -@opindex mserialize-volatile -@itemx -mno-serialize-volatile -@opindex mno-serialize-volatile -@cindex sequential consistency on 88k -Do, or don't, generate code to guarantee sequential consistency -of volatile memory references. By default, consistency is -guaranteed. - -The order of memory references made by the MC88110 processor does -not always match the order of the instructions requesting those -references. In particular, a load instruction may execute before -a preceding store instruction. Such reordering violates -sequential consistency of volatile memory references, when there -are multiple processors. When consistency must be guaranteed, -GCC generates special instructions, as needed, to force -execution in the proper order. - -The MC88100 processor does not reorder memory references and so -always provides sequential consistency. However, by default, GCC -generates the special instructions to guarantee consistency -even when you use @option{-m88100}, so that the code may be run on an -MC88110 processor. If you intend to run your code only on the -MC88100 processor, you may use @option{-mno-serialize-volatile}. - -The extra code generated to guarantee consistency may affect the -performance of your application. If you know that you can safely -forgo this guarantee, you may use @option{-mno-serialize-volatile}. - -@item -msvr4 -@itemx -msvr3 -@opindex msvr4 -@opindex msvr3 -@cindex assembler syntax, 88k -@cindex SVr4 -Turn on (@option{-msvr4}) or off (@option{-msvr3}) compiler extensions -related to System V release 4 (SVr4). This controls the following: - -@enumerate -@item -Which variant of the assembler syntax to emit. -@item -@option{-msvr4} makes the C preprocessor recognize @samp{#pragma weak} -that is used on System V release 4. -@item -@option{-msvr4} makes GCC issue additional declaration directives used in -SVr4. -@end enumerate - -@option{-msvr4} is the default for the m88k-motorola-sysv4 configuration. -@option{-msvr3} is the default for all other m88k configurations. - -@item -mversion-03.00 -@opindex mversion-03.00 -This option is obsolete, and is ignored. -@c ??? which asm syntax better for GAS? option there too? - -@item -mno-check-zero-division -@itemx -mcheck-zero-division -@opindex mno-check-zero-division -@opindex mcheck-zero-division -@cindex zero division on 88k -Do, or don't, generate code to guarantee that integer division by -zero will be detected. By default, detection is guaranteed. - -Some models of the MC88100 processor fail to trap upon integer -division by zero under certain conditions. By default, when -compiling code that might be run on such a processor, GCC -generates code that explicitly checks for zero-valued divisors -and traps with exception number 503 when one is detected. Use of -@option{-mno-check-zero-division} suppresses such checking for code -generated to run on an MC88100 processor. - -GCC assumes that the MC88110 processor correctly detects all instances -of integer division by zero. When @option{-m88110} is specified, no -explicit checks for zero-valued divisors are generated, and both -@option{-mcheck-zero-division} and @option{-mno-check-zero-division} are -ignored. +@item -mdebug +@opindex mdebug +Makes the M32R specific code in the compiler display some statistics +that might help in debugging programs. + +@item -malign-loops +@opindex malign-loops +Align all loops to a 32-byte boundary. + +@item -mno-align-loops +@opindex mno-align-loops +Do not enforce a 32-byte alignment for loops. This is the default. + +@item -missue-rate=@var{number} +@opindex missue-rate=@var{number} +Issue @var{number} instructions per cycle. @var{number} can only be 1 +or 2. + +@item -mbranch-cost=@var{number} +@opindex mbranch-cost=@var{number} +@var{number} can only be 1 or 2. If it is 1 then branches will be +preferred over conditional code, if it is 2, then the opposite will +apply. + +@item -mflush-trap=@var{number} +@opindex mflush-trap=@var{number} +Specifies the trap number to use to flush the cache. The default is +12. Valid numbers are between 0 and 15 inclusive. + +@item -mno-flush-trap +@opindex mno-flush-trap +Specifies that the cache cannot be flushed by using a trap. + +@item -mflush-func=@var{name} +@opindex mflush-func=@var{name} +Specifies the name of the operating system function to call to flush +the cache. The default is @emph{_flush_cache}, but a function call +will only be used if a trap is not available. + +@item -mno-flush-func +@opindex mno-flush-func +Indicates that there is no OS function for flushing the cache. -@item -muse-div-instruction -@opindex muse-div-instruction -@cindex divide instruction, 88k -Use the div instruction for signed integer division on the -MC88100 processor. By default, the div instruction is not used. - -On the MC88100 processor the signed integer division instruction -div) traps to the operating system on a negative operand. The -operating system transparently completes the operation, but at a -large cost in execution time. By default, when compiling code -that might be run on an MC88100 processor, GCC emulates signed -integer division using the unsigned integer division instruction -divu), thereby avoiding the large penalty of a trap to the -operating system. Such emulation has its own, smaller, execution -cost in both time and space. To the extent that your code's -important signed integer division operations are performed on two -nonnegative operands, it may be desirable to use the div -instruction directly. - -On the MC88110 processor the div instruction (also known as the -divs instruction) processes negative operands without trapping to -the operating system. When @option{-m88110} is specified, -@option{-muse-div-instruction} is ignored, and the div instruction is used -for signed integer division. - -Note that the result of dividing @code{INT_MIN} by @minus{}1 is undefined. In -particular, the behavior of such a division with and without -@option{-muse-div-instruction} may differ. - -@item -mtrap-large-shift -@itemx -mhandle-large-shift -@opindex mtrap-large-shift -@opindex mhandle-large-shift -@cindex bit shift overflow (88k) -@cindex large bit shifts (88k) -Include code to detect bit-shifts of more than 31 bits; respectively, -trap such shifts or emit code to handle them properly. By default GCC -makes no special provision for large bit shifts. - -@item -mwarn-passed-structs -@opindex mwarn-passed-structs -@cindex structure passing (88k) -Warn when a function passes a struct as an argument or result. -Structure-passing conventions have changed during the evolution of the C -language, and are often the source of portability problems. By default, -GCC issues no such warning. @end table -@c break page here to avoid unsightly interparagraph stretch. -@c -zw, 2001-8-17 -@page - @node RS/6000 and PowerPC Options @subsection IBM RS/6000 and PowerPC Options @cindex RS/6000 and PowerPC Options @@ -6736,12 +7045,15 @@ should normally not specify either @option{-mnew-mnemonics} or @opindex mcpu Set architecture type, register usage, choice of mnemonics, and instruction scheduling parameters for machine type @var{cpu_type}. -Supported values for @var{cpu_type} are @samp{rios}, @samp{rios1}, -@samp{rsc}, @samp{rios2}, @samp{rs64a}, @samp{601}, @samp{602}, -@samp{603}, @samp{603e}, @samp{604}, @samp{604e}, @samp{620}, -@samp{630}, @samp{740}, @samp{7400}, @samp{7450}, @samp{750}, -@samp{power}, @samp{power2}, @samp{powerpc}, @samp{403}, @samp{505}, -@samp{801}, @samp{821}, @samp{823}, and @samp{860} and @samp{common}. +Supported values for @var{cpu_type} are @samp{401}, @samp{403}, +@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505}, +@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604}, +@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400}, +@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823}, +@samp{860}, @samp{970}, @samp{common}, @samp{ec603e}, @samp{G3}, +@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3}, +@samp{power4}, @samp{power5}, @samp{powerpc}, @samp{powerpc64}, +@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64a}. @option{-mcpu=common} selects a completely generic processor. Code generated under this option will run on any POWER or PowerPC processor. @@ -6759,43 +7071,23 @@ The other options specify a specific processor. Code generated under those options will run best on that processor, and may not run at all on others. -The @option{-mcpu} options automatically enable or disable other -@option{-m} options as follows: - -@table @samp -@item common -@option{-mno-power}, @option{-mno-powerpc} - -@item power -@itemx power2 -@itemx rios1 -@itemx rios2 -@itemx rsc -@option{-mpower}, @option{-mno-powerpc}, @option{-mno-new-mnemonics} - -@item powerpc -@itemx rs64a -@itemx 602 -@itemx 603 -@itemx 603e -@itemx 604 -@itemx 620 -@itemx 630 -@itemx 740 -@itemx 7400 -@itemx 7450 -@itemx 750 -@itemx 505 -@option{-mno-power}, @option{-mpowerpc}, @option{-mnew-mnemonics} - -@item 601 -@option{-mpower}, @option{-mpowerpc}, @option{-mnew-mnemonics} - -@item 403 -@itemx 821 -@itemx 860 -@option{-mno-power}, @option{-mpowerpc}, @option{-mnew-mnemonics}, @option{-msoft-float} -@end table +The @option{-mcpu} options automatically enable or disable the +following options: @option{-maltivec}, @option{-mhard-float}, +@option{-mmfcrf}, @option{-mmultiple}, @option{-mnew-mnemonics}, +@option{-mpower}, @option{-mpower2}, @option{-mpowerpc64}, +@option{-mpowerpc-gpopt}, @option{-mpowerpc-gfxopt}, +@option{-mstring}. The particular options set for any particular CPU +will vary between compiler versions, depending on what setting seems +to produce optimal code for that CPU; it doesn't necessarily reflect +the actual hardware's capabilities. If you wish to set an individual +option to a particular value, you may specify it after the +@option{-mcpu} option, like @samp{-mcpu=970 -mno-altivec}. + +On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are +not enabled or disabled by the @option{-mcpu} option at present, since +AIX does not have full support for these options. You may still +enable or disable them individually if you're sure it'll work in your +environment. @item -mtune=@var{cpu_type} @opindex mtune @@ -6831,6 +7123,19 @@ Disable Booke SPE ABI extensions for the current ABI. @opindex misel This switch enables or disables the generation of ISEL instructions. +@item -mspe=@var{yes/no} +@itemx -mspe +@opindex mspe +This switch enables or disables the generation of SPE simd +instructions. + +@item -mfloat-gprs=@var{yes/no} +@itemx -mfloat-gprs +@opindex mfloat-gprs +This switch enables or disables the generation of floating point +operations on the general purpose registers for architectures that +support it. This option is currently only available on the MPC8540. + @item -mfull-toc @itemx -mno-fp-in-toc @itemx -mno-sum-in-toc @@ -6900,6 +7205,16 @@ appropriate directory location. The Parallel Environment does not support threads, so the @option{-mpe} option and the @option{-pthread} option are incompatible. +@item -malign-natural +@itemx -malign-power +@opindex malign-natural +@opindex malign-power +On AIX, Darwin, and 64-bit PowerPC GNU/Linux, the option +@option{-malign-natural} overrides the ABI-defined alignment of larger +types, such as floating-point doubles, on their natural size-based boundary. +The option @option{-malign-power} instructs GCC to follow the ABI-specified +alignment rules. GCC defaults to the standard alignment defined in the ABI. + @item -msoft-float @itemx -mhard-float @opindex msoft-float @@ -7017,6 +7332,46 @@ On System V.4 and embedded PowerPC systems compile code for the processor in big endian mode. The @option{-mbig-endian} option is the same as @option{-mbig}. +@item -mdynamic-no-pic +@opindex mdynamic-no-pic +On Darwin and Mac OS X systems, compile code so that it is not +relocatable, but that its external references are relocatable. The +resulting code is suitable for applications, but not shared +libraries. + +@item -mprioritize-restricted-insns=@var{priority} +@opindex mprioritize-restricted-insns +This option controls the priority that is assigned to +dispatch-slot restricted instructions during the second scheduling +pass. The argument @var{priority} takes the value @var{0/1/2} to assign +@var{no/highest/second-highest} priority to dispatch slot restricted +instructions. + +@item -msched-costly-dep=@var{dependence_type} +@opindex msched-costly-dep +This option controls which dependences are considered costly +by the target during instruction scheduling. The argument +@var{dependence_type} takes one of the following values: +@var{no}: no dependence is costly, +@var{all}: all dependences are costly, +@var{true_store_to_load}: a true dependence from store to load is costly, +@var{store_to_load}: any dependence from store to load is costly, +@var{number}: any dependence which latency >= @var{number} is costly. + +@item -minsert-sched-nops=@var{scheme} +@opindex minsert-sched-nops +This option controls which nop insertion scheme will be used during +the second scheduling pass. The argument @var{scheme} takes one of the +following values: +@var{no}: Don't insert nops. +@var{pad}: Pad with nops any dispatch group which has vacant issue slots, +according to the scheduler's grouping. +@var{regroup_exact}: Insert nops to force costly dependent insns into +separate groups. Insert exactly as many nops as needed to force an insn +to a new group, according to the estimated processor grouping. +@var{number}: Insert nops to force costly dependent insns into +separate groups. Insert @var{number} nops to force an insn to a new group. + @item -mcall-sysv @opindex mcall-sysv On System V.4 and embedded PowerPC systems compile code using calling @@ -7032,12 +7387,6 @@ Specify both @option{-mcall-sysv} and @option{-meabi} options. @opindex mcall-sysv-noeabi Specify both @option{-mcall-sysv} and @option{-mno-eabi} options. -@item -mcall-aix -@opindex mcall-aix -On System V.4 and embedded PowerPC systems compile code using calling -conventions that are similar to those used on AIX@. This is the -default if you configured GCC using @samp{powerpc-*-eabiaix}. - @item -mcall-solaris @opindex mcall-solaris On System V.4 and embedded PowerPC systems compile code for the Solaris @@ -7223,6 +7572,10 @@ generate slower code. As of this writing, the AIX linker can do this, as can the GNU linker for PowerPC/64. It is planned to add this feature to the GNU linker for 32-bit PowerPC systems as well. +On Mach-O (Darwin) systems, this option directs the compiler emit to +the glue for every direct call, and the Darwin linker decides whether +to use or discard it. + In the future, we may cause GCC to ignore all longcall specifications when the linker is known to generate glue. @@ -7241,8 +7594,8 @@ These options are defined for all architectures running the Darwin operating system. They are useful for compatibility with other Mac OS compilers. @table @gcctabopt -@item -all_load -@opindex all_load +@item -all_load +@opindex all_load Loads all members of static archive libraries. See man ld(1) for more information. @@ -7256,7 +7609,7 @@ to be fatal. Causes the output file to be marked such that the dynamic linker will bind all undefined references when the file is loaded or launched. -@item -bundle +@item -bundle @opindex bundle Produce a Mach-o bundle format file. See man ld(1) for more information. @@ -7267,64 +7620,65 @@ This specifies the @var{executable} that will be loading the build output file being linked. See man ld(1) for more information. @item -allowable_client @var{client_name} -@item -arch_only - -@item -client_name -@item -compatibility_version -@item -current_version -@item -dependency-file -@item -dylib_file -@item -dylinker_install_name -@item -dynamic -@item -dynamiclib -@item -exported_symbols_list -@item -filelist -@item -flat_namespace -@item -force_cpusubtype_ALL -@item -force_flat_namespace -@item -headerpad_max_install_names -@item -image_base -@item -init -@item -install_name -@item -keep_private_externs -@item -multi_module -@item -multiply_defined -@item -multiply_defined_unused -@item -noall_load -@item -nomultidefs -@item -noprebind -@item -noseglinkedit -@item -pagezero_size -@item -prebind -@item -prebind_all_twolevel_modules -@item -private_bundle -@item -read_only_relocs -@item -sectalign -@item -sectobjectsymbols -@item -whyload -@item -seg1addr -@item -sectcreate -@item -sectobjectsymbols -@item -sectorder -@item -seg_addr_table -@item -seg_addr_table_filename -@item -seglinkedit -@item -segprot -@item -segs_read_only_addr -@item -segs_read_write_addr -@item -single_module -@item -static -@item -sub_library -@item -sub_umbrella -@item -twolevel_namespace -@item -umbrella -@item -undefined -@item -unexported_symbols_list -@item -weak_reference_mismatches -@item -whatsloaded +@itemx -arch_only + +@itemx -client_name +@itemx -compatibility_version +@itemx -current_version +@itemx -dependency-file +@itemx -dylib_file +@itemx -dylinker_install_name +@itemx -dynamic +@itemx -dynamiclib +@itemx -exported_symbols_list +@itemx -filelist +@itemx -flat_namespace +@itemx -force_cpusubtype_ALL +@itemx -force_flat_namespace +@itemx -headerpad_max_install_names +@itemx -image_base +@itemx -init +@itemx -install_name +@itemx -keep_private_externs +@itemx -multi_module +@itemx -multiply_defined +@itemx -multiply_defined_unused +@itemx -noall_load +@itemx -nofixprebinding +@itemx -nomultidefs +@itemx -noprebind +@itemx -noseglinkedit +@itemx -pagezero_size +@itemx -prebind +@itemx -prebind_all_twolevel_modules +@itemx -private_bundle +@itemx -read_only_relocs +@itemx -sectalign +@itemx -sectobjectsymbols +@itemx -whyload +@itemx -seg1addr +@itemx -sectcreate +@itemx -sectobjectsymbols +@itemx -sectorder +@itemx -seg_addr_table +@itemx -seg_addr_table_filename +@itemx -seglinkedit +@itemx -segprot +@itemx -segs_read_only_addr +@itemx -segs_read_write_addr +@itemx -single_module +@itemx -static +@itemx -sub_library +@itemx -sub_umbrella +@itemx -twolevel_namespace +@itemx -umbrella +@itemx -undefined +@itemx -unexported_symbols_list +@itemx -weak_reference_mismatches +@itemx -whatsloaded @opindex allowable_client -@opindex arch_only +@opindex arch_only @opindex client_name @opindex compatibility_version @opindex current_version @@ -7334,34 +7688,35 @@ output file being linked. See man ld(1) for more information. @opindex dynamic @opindex dynamiclib @opindex exported_symbols_list -@opindex filelist -@opindex flat_namespace +@opindex filelist +@opindex flat_namespace @opindex force_cpusubtype_ALL @opindex force_flat_namespace @opindex headerpad_max_install_names @opindex image_base -@opindex init +@opindex init @opindex install_name @opindex keep_private_externs -@opindex multi_module +@opindex multi_module @opindex multiply_defined -@opindex multiply_defined_unused -@opindex noall_load -@opindex nomultidefs +@opindex multiply_defined_unused +@opindex noall_load +@opindex nofixprebinding +@opindex nomultidefs @opindex noprebind -@opindex noseglinkedit +@opindex noseglinkedit @opindex pagezero_size @opindex prebind @opindex prebind_all_twolevel_modules -@opindex private_bundle +@opindex private_bundle @opindex read_only_relocs -@opindex sectalign -@opindex sectobjectsymbols -@opindex whyload +@opindex sectalign +@opindex sectobjectsymbols +@opindex whyload @opindex seg1addr -@opindex sectcreate -@opindex sectobjectsymbols -@opindex sectorder +@opindex sectcreate +@opindex sectobjectsymbols +@opindex sectorder @opindex seg_addr_table @opindex seg_addr_table_filename @opindex seglinkedit @@ -7379,85 +7734,44 @@ output file being linked. See man ld(1) for more information. @opindex weak_reference_mismatches @opindex whatsloaded -This options are available for Darwin linker. Darwin linker man page +These options are available for Darwin linker. Darwin linker man page describes them in detail. @end table -@node RT Options -@subsection IBM RT Options -@cindex RT options -@cindex IBM RT options - -These @samp{-m} options are defined for the IBM RT PC: - -@table @gcctabopt -@item -min-line-mul -@opindex min-line-mul -Use an in-line code sequence for integer multiplies. This is the -default. - -@item -mcall-lib-mul -@opindex mcall-lib-mul -Call @code{lmul$$} for integer multiples. - -@item -mfull-fp-blocks -@opindex mfull-fp-blocks -Generate full-size floating point data blocks, including the minimum -amount of scratch space recommended by IBM@. This is the default. - -@item -mminimum-fp-blocks -@opindex mminimum-fp-blocks -Do not include extra scratch space in floating point data blocks. This -results in smaller code, but slower execution, since scratch space must -be allocated dynamically. - -@cindex @file{stdarg.h} and RT PC -@item -mfp-arg-in-fpregs -@opindex mfp-arg-in-fpregs -Use a calling sequence incompatible with the IBM calling convention in -which floating point arguments are passed in floating point registers. -Note that @code{stdarg.h} will not work with floating point operands -if this option is specified. - -@item -mfp-arg-in-gregs -@opindex mfp-arg-in-gregs -Use the normal calling convention for floating point arguments. This is -the default. - -@item -mhc-struct-return -@opindex mhc-struct-return -Return structures of more than one word in memory, rather than in a -register. This provides compatibility with the MetaWare HighC (hc) -compiler. Use the option @option{-fpcc-struct-return} for compatibility -with the Portable C Compiler (pcc). - -@item -mnohc-struct-return -@opindex mnohc-struct-return -Return some structures of more than one word in registers, when -convenient. This is the default. For compatibility with the -IBM-supplied compilers, use the option @option{-fpcc-struct-return} or the -option @option{-mhc-struct-return}. -@end table - @node MIPS Options @subsection MIPS Options @cindex MIPS options -These @samp{-m} options are defined for the MIPS family of computers: - @table @gcctabopt +@item -EB +@opindex EB +Generate big-endian code. + +@item -EL +@opindex EL +Generate little-endian code. This is the default for @samp{mips*el-*-*} +configurations. + @item -march=@var{arch} @opindex march Generate code that will run on @var{arch}, which can be the name of a -generic MIPS ISA, or the name of a particular processor. The ISA names -are: @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4}, @samp{mips32} -and @samp{mips64}. The processor names are: @samp{r2000}, -@samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{vr4100}, @samp{vr4300}, -@samp{r4400}, @samp{r4600}, @samp{r4650}, @samp{vr5000}, @samp{r6000}, -@samp{r8000}, @samp{4kc}, @samp{4kp}, @samp{5kc}, @samp{20kc}, -@samp{orion}, and @samp{sb1}. The special value @samp{from-abi} selects the +generic MIPS ISA, or the name of a particular processor. +The ISA names are: +@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4}, +@samp{mips32}, @samp{mips32r2}, and @samp{mips64}. +The processor names are: +@samp{4kc}, @samp{4kp}, @samp{5kc}, @samp{20kc}, +@samp{m4k}, +@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400}, +@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000}, @samp{rm7000}, +@samp{rm9000}, +@samp{orion}, +@samp{sb1}, +@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4300}, +@samp{vr5000}, @samp{vr5400} and @samp{vr5500}. +The special value @samp{from-abi} selects the most compatible architecture for the selected ABI (that is, @samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@. @@ -7516,289 +7830,268 @@ Equivalent to @samp{-march=mips4}. @opindex mips32 Equivalent to @samp{-march=mips32}. +@item -mips32r2 +@opindex mips32r2 +Equivalent to @samp{-march=mips32r2}. + @item -mips64 @opindex mips64 Equivalent to @samp{-march=mips64}. -@item -mfused-madd -@itemx -mno-fused-madd -@opindex mfused-madd -@opindex mno-fused-madd -Generate code that uses (does not use) the floating point multiply and -accumulate instructions, when they are available. These instructions -are generated by default if they are available, but this may be -undesirable if the extra precision causes problems or on certain chips -in the mode where denormals are rounded to zero where denormals -generated by multiply and accumulate instructions cause exceptions -anyway. +@item -mips16 +@itemx -mno-mips16 +@opindex mips16 +@opindex mno-mips16 +Use (do not use) the MIPS16 ISA. -@item -mfp32 -@opindex mfp32 -Assume that floating point registers are 32 bits wide. +@item -mabi=32 +@itemx -mabi=o64 +@itemx -mabi=n32 +@itemx -mabi=64 +@itemx -mabi=eabi +@opindex mabi=32 +@opindex mabi=o64 +@opindex mabi=n32 +@opindex mabi=64 +@opindex mabi=eabi +Generate code for the given ABI@. -@item -mfp64 -@opindex mfp64 -Assume that floating point registers are 64 bits wide. +Note that the EABI has a 32-bit and a 64-bit variant. GCC normally +generates 64-bit code when you select a 64-bit architecture, but you +can use @option{-mgp32} to get 32-bit code instead. + +@item -mabicalls +@itemx -mno-abicalls +@opindex mabicalls +@opindex mno-abicalls +Generate (do not generate) SVR4-style position-independent code. +@option{-mabicalls} is the default for SVR4-based systems. + +@item -mxgot +@itemx -mno-xgot +@opindex mxgot +@opindex mno-xgot +Lift (do not lift) the usual restrictions on the size of the global +offset table. + +GCC normally uses a single instruction to load values from the GOT. +While this is relatively efficient, it will only work if the GOT +is smaller than about 64k. Anything larger will cause the linker +to report an error such as: + +@cindex relocation truncated to fit (MIPS) +@smallexample +relocation truncated to fit: R_MIPS_GOT16 foobar +@end smallexample + +If this happens, you should recompile your code with @option{-mxgot}. +It should then work with very large GOTs, although it will also be +less efficient, since it will take three instructions to fetch the +value of a global symbol. + +Note that some linkers can create multiple GOTs. If you have such a +linker, you should only need to use @option{-mxgot} when a single object +file accesses more than 64k's worth of GOT entries. Very few do. + +These options have no effect unless GCC is generating position +independent code. + +@item -membedded-pic +@itemx -mno-embedded-pic +@opindex membedded-pic +@opindex mno-embedded-pic +Generate (do not generate) position-independent code suitable for some +embedded systems. All calls are made using PC relative addresses, and +all data is addressed using the $gp register. No more than 65536 +bytes of global data may be used. This requires GNU as and GNU ld, +which do most of the work. @item -mgp32 @opindex mgp32 -Assume that general purpose registers are 32 bits wide. +Assume that general-purpose registers are 32 bits wide. @item -mgp64 @opindex mgp64 -Assume that general purpose registers are 64 bits wide. +Assume that general-purpose registers are 64 bits wide. + +@item -mfp32 +@opindex mfp32 +Assume that floating-point registers are 32 bits wide. + +@item -mfp64 +@opindex mfp64 +Assume that floating-point registers are 64 bits wide. + +@item -mhard-float +@opindex mhard-float +Use floating-point coprocessor instructions. + +@item -msoft-float +@opindex msoft-float +Do not use floating-point coprocessor instructions. Implement +floating-point calculations using library calls instead. + +@item -msingle-float +@opindex msingle-float +Assume that the floating-point coprocessor only supports single-precision +operations. + +@itemx -mdouble-float +@opindex mdouble-float +Assume that the floating-point coprocessor supports double-precision +operations. This is the default. @item -mint64 @opindex mint64 -Force int and long types to be 64 bits wide. See @option{-mlong32} for an -explanation of the default, and the width of pointers. +Force @code{int} and @code{long} types to be 64 bits wide. See +@option{-mlong32} for an explanation of the default and the way +that the pointer size is determined. @item -mlong64 @opindex mlong64 -Force long types to be 64 bits wide. See @option{-mlong32} for an -explanation of the default, and the width of pointers. +Force @code{long} types to be 64 bits wide. See @option{-mlong32} for +an explanation of the default and the way that the pointer size is +determined. @item -mlong32 @opindex mlong32 -Force long, int, and pointer types to be 32 bits wide. +Force @code{long}, @code{int}, and pointer types to be 32 bits wide. -The default size of ints, longs and pointers depends on the ABI@. All -the supported ABIs use 32-bit ints. The n64 ABI uses 64-bit longs, as -does the 64-bit Cygnus EABI; the others use 32-bit longs. Pointers -are the same size as longs, or the same size as integer registers, -whichever is smaller. +The default size of @code{int}s, @code{long}s and pointers depends on +the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI +uses 64-bit @code{long}s, as does the 64-bit EABI; the others use +32-bit @code{long}s. Pointers are the same size as @code{long}s, +or the same size as integer registers, whichever is smaller. -@item -mabi=32 -@itemx -mabi=o64 -@itemx -mabi=n32 -@itemx -mabi=64 -@itemx -mabi=eabi -@itemx -mabi=meabi -@opindex mabi=32 -@opindex mabi=o64 -@opindex mabi=n32 -@opindex mabi=64 -@opindex mabi=eabi -@opindex mabi=meabi -Generate code for the given ABI@. +@item -G @var{num} +@opindex G +@cindex smaller data references (MIPS) +@cindex gp-relative references (MIPS) +Put global and static items less than or equal to @var{num} bytes into +the small data or bss section instead of the normal data or bss section. +This allows the data to be accessed using a single instruction. -Note that there are two embedded ABIs: @option{-mabi=eabi} -selects the one defined by Cygnus while @option{-meabi=meabi} -selects the one defined by MIPS@. Both these ABIs have -32-bit and 64-bit variants. Normally, GCC will generate -64-bit code when you select a 64-bit architecture, but you -can use @option{-mgp32} to get 32-bit code instead. +All modules should be compiled with the same @option{-G @var{num}} +value. -@item -mmips-as -@opindex mmips-as -Generate code for the MIPS assembler, and invoke @file{mips-tfile} to -add normal debug information. This is the default for all -platforms except for the OSF/1 reference platform, using the OSF/rose -object format. If the either of the @option{-gstabs} or @option{-gstabs+} -switches are used, the @file{mips-tfile} program will encapsulate the -stabs within MIPS ECOFF@. +@item -membedded-data +@itemx -mno-embedded-data +@opindex membedded-data +@opindex mno-embedded-data +Allocate variables to the read-only data section first if possible, then +next in the small data section if possible, otherwise in data. This gives +slightly slower code than the default, but reduces the amount of RAM required +when executing, and thus may be preferred for some embedded systems. -@item -mgas -@opindex mgas -Generate code for the GNU assembler. This is the default on the OSF/1 -reference platform, using the OSF/rose object format. Also, this is -the default if the configure option @option{--with-gnu-as} is used. +@item -muninit-const-in-rodata +@itemx -mno-uninit-const-in-rodata +@opindex muninit-const-in-rodata +@opindex mno-uninit-const-in-rodata +Put uninitialized @code{const} variables in the read-only data section. +This option is only meaningful in conjunction with @option{-membedded-data}. @item -msplit-addresses @itemx -mno-split-addresses @opindex msplit-addresses @opindex mno-split-addresses -Generate code to load the high and low parts of address constants separately. -This allows GCC to optimize away redundant loads of the high order -bits of addresses. This optimization requires GNU as and GNU ld. -This optimization is enabled by default for some embedded targets where -GNU as and GNU ld are standard. +Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler +relocation operators. This option has been superceded by +@option{-mexplicit-relocs} but is retained for backwards compatibility. + +@item -mexplicit-relocs +@itemx -mno-explicit-relocs +@opindex mexplicit-relocs +@opindex mno-explicit-relocs +Use (do not use) assembler relocation operators when dealing with symbolic +addresses. The alternative, selected by @option{-mno-explicit-relocs}, +is to use assembler macros instead. + +@option{-mexplicit-relocs} is usually the default if GCC was +configured to use an assembler that supports relocation operators. +However, there are two exceptions: + +@itemize @bullet +@item +GCC is not yet able to generate explicit relocations for the combination +of @option{-mabi=64} and @option{-mno-abicalls}. This will be addressed +in a future release. + +@item +The combination of @option{-mabicalls} and @option{-fno-unit-at-a-time} +implies @option{-mno-explicit-relocs} unless explicitly overridden. +This is because, when generating abicalls, the choice of relocation +depends on whether a symbol is local or global. In some rare cases, +GCC will not be able to decide this until the whole compilation unit +has been read. +@end itemize @item -mrnames @itemx -mno-rnames @opindex mrnames @opindex mno-rnames -The @option{-mrnames} switch says to output code using the MIPS software -names for the registers, instead of the hardware names (ie, @var{a0} -instead of @var{$4}). The only known assembler that supports this option -is the Algorithmics assembler. - -@item -mgpopt -@itemx -mno-gpopt -@opindex mgpopt -@opindex mno-gpopt -The @option{-mgpopt} switch says to write all of the data declarations -before the instructions in the text section, this allows the MIPS -assembler to generate one word memory references instead of using two -words for short global or static data items. This is on by default if -optimization is selected. - -@item -mstats -@itemx -mno-stats -@opindex mstats -@opindex mno-stats -For each non-inline function processed, the @option{-mstats} switch -causes the compiler to emit one line to the standard error file to -print statistics about the program (number of registers saved, stack -size, etc.). +Generate (do not generate) code that refers to registers using their +software names. The default is @option{-mno-rnames}, which tells GCC +to use hardware names like @samp{$4} instead of software names like +@samp{a0}. The only assembler known to support @option{-rnames} is +the Algorithmics assembler. + +@item -mcheck-zero-division +@itemx -mno-check-zero-division +@opindex mcheck-zero-division +@opindex mno-check-zero-division +Trap (do not trap) on integer division by zero. The default is +@option{-mcheck-zero-division}. @item -mmemcpy @itemx -mno-memcpy @opindex mmemcpy @opindex mno-memcpy -The @option{-mmemcpy} switch makes all block moves call the appropriate -string function (@samp{memcpy} or @samp{bcopy}) instead of possibly -generating inline code. - -@item -mmips-tfile -@itemx -mno-mips-tfile -@opindex mmips-tfile -@opindex mno-mips-tfile -The @option{-mno-mips-tfile} switch causes the compiler not -postprocess the object file with the @file{mips-tfile} program, -after the MIPS assembler has generated it to add debug support. If -@file{mips-tfile} is not run, then no local variables will be -available to the debugger. In addition, @file{stage2} and -@file{stage3} objects will have the temporary file names passed to the -assembler embedded in the object file, which means the objects will -not compare the same. The @option{-mno-mips-tfile} switch should only -be used when there are bugs in the @file{mips-tfile} program that -prevents compilation. - -@item -msoft-float -@opindex msoft-float -Generate output containing library calls for floating point. -@strong{Warning:} the requisite libraries are not part of GCC@. -Normally the facilities of the machine's usual C compiler are used, but -this can't be done directly in cross-compilation. You must make your -own arrangements to provide suitable library functions for -cross-compilation. - -@item -mhard-float -@opindex mhard-float -Generate output containing floating point instructions. This is the -default if you use the unmodified sources. - -@item -mabicalls -@itemx -mno-abicalls -@opindex mabicalls -@opindex mno-abicalls -Emit (or do not emit) the pseudo operations @samp{.abicalls}, -@samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for -position independent code. +Force (do not force) the use of @code{memcpy()} for non-trivial block +moves. The default is @option{-mno-memcpy}, which allows GCC to inline +most constant-sized copies. @item -mlong-calls @itemx -mno-long-calls @opindex mlong-calls @opindex mno-long-calls -Do all calls with the @samp{JALR} instruction, which requires -loading up a function's address into a register before the call. -You need to use this switch, if you call outside of the current -512 megabyte segment to functions that are not through pointers. - -@item -mhalf-pic -@itemx -mno-half-pic -@opindex mhalf-pic -@opindex mno-half-pic -Put pointers to extern references into the data section and load them -up, rather than put the references in the text section. +Disable (do not disable) use of the @code{jal} instruction. Calling +functions using @code{jal} is more efficient but requires the caller +and callee to be in the same 256 megabyte segment. -@item -membedded-pic -@itemx -mno-embedded-pic -@opindex membedded-pic -@opindex mno-embedded-pic -Generate PIC code suitable for some embedded systems. All calls are -made using PC relative address, and all data is addressed using the $gp -register. No more than 65536 bytes of global data may be used. This -requires GNU as and GNU ld which do most of the work. This currently -only works on targets which use ECOFF; it does not work with ELF@. - -@item -membedded-data -@itemx -mno-embedded-data -@opindex membedded-data -@opindex mno-embedded-data -Allocate variables to the read-only data section first if possible, then -next in the small data section if possible, otherwise in data. This gives -slightly slower code than the default, but reduces the amount of RAM required -when executing, and thus may be preferred for some embedded systems. - -@item -muninit-const-in-rodata -@itemx -mno-uninit-const-in-rodata -@opindex muninit-const-in-rodata -@opindex mno-uninit-const-in-rodata -When used together with @option{-membedded-data}, it will always store uninitialized -const variables in the read-only data section. - -@item -msingle-float -@itemx -mdouble-float -@opindex msingle-float -@opindex mdouble-float -The @option{-msingle-float} switch tells gcc to assume that the floating -point coprocessor only supports single precision operations, as on the -@samp{r4650} chip. The @option{-mdouble-float} switch permits gcc to use -double precision operations. This is the default. +This option has no effect on abicalls code. The default is +@option{-mno-long-calls}. @item -mmad @itemx -mno-mad @opindex mmad @opindex mno-mad -Permit use of the @samp{mad}, @samp{madu} and @samp{mul} instructions, -as on the @samp{r4650} chip. - -@item -m4650 -@opindex m4650 -Turns on @option{-msingle-float}, @option{-mmad}, and, at least for now, -@option{-mcpu=r4650}. - -@item -mips16 -@itemx -mno-mips16 -@opindex mips16 -@opindex mno-mips16 -Enable 16-bit instructions. +Enable (disable) use of the @code{mad}, @code{madu} and @code{mul} +instructions, as provided by the R4650 ISA. -@item -mentry -@opindex mentry -Use the entry and exit pseudo ops. This option can only be used with -@option{-mips16}. - -@item -EL -@opindex EL -Compile code for the processor in little endian mode. -The requisite libraries are assumed to exist. - -@item -EB -@opindex EB -Compile code for the processor in big endian mode. -The requisite libraries are assumed to exist. +@item -mfused-madd +@itemx -mno-fused-madd +@opindex mfused-madd +@opindex mno-fused-madd +Enable (disable) use of the floating point multiply-accumulate +instructions, when they are available. The default is +@option{-mfused-madd}. -@item -G @var{num} -@opindex G -@cindex smaller data references (MIPS) -@cindex gp-relative references (MIPS) -Put global and static items less than or equal to @var{num} bytes into -the small data or bss sections instead of the normal data or bss -section. This allows the assembler to emit one word memory reference -instructions based on the global pointer (@var{gp} or @var{$28}), -instead of the normal two words used. By default, @var{num} is 8 when -the MIPS assembler is used, and 0 when the GNU assembler is used. The -@option{-G @var{num}} switch is also passed to the assembler and linker. -All modules should be compiled with the same @option{-G @var{num}} -value. +When multiply-accumulate instructions are used, the intermediate +product is calculated to infinite precision and is not subject to +the FCSR Flush to Zero bit. This may be undesirable in some +circumstances. @item -nocpp @opindex nocpp Tell the MIPS assembler to not run its preprocessor over user assembler files (with a @samp{.s} suffix) when assembling them. -@item -mfix7000 -@opindex mfix7000 -Pass an option to gas which will cause nops to be inserted if -the read of the destination register of an mfhi or mflo instruction -occurs in the following two instructions. - -@item -no-crt0 -@opindex no-crt0 -Do not include the default crt0. +@item -mfix-sb1 +@itemx -mno-fix-sb1 +@opindex mfix-sb1 +Work around certain SB-1 CPU core errata. +(This flag currently works around the SB-1 revision 2 +``F1'' and ``F2'' floating point errata.) @item -mflush-func=@var{func} @itemx -mno-flush-func @@ -7808,7 +8101,7 @@ call any such function. If called, the function must take the same arguments as the common @code{_flush_func()}, that is, the address of the memory range for which the cache is being flushed, the size of the memory range, and the number 3 (to flush both caches). The default -depends on the target gcc was configured for, but commonly is either +depends on the target GCC was configured for, but commonly is either @samp{_flush_func} or @samp{__cpu_flush}. @item -mbranch-likely @@ -7835,28 +8128,79 @@ These @samp{-m} options are defined for the i386 and x86-64 family of computers: @table @gcctabopt -@item -mcpu=@var{cpu-type} -@opindex mcpu +@item -mtune=@var{cpu-type} +@opindex mtune Tune to @var{cpu-type} everything applicable about the generated code, except for the ABI and the set of available instructions. The choices for -@var{cpu-type} are @samp{i386}, @samp{i486}, @samp{i586}, @samp{i686}, -@samp{pentium}, @samp{pentium-mmx}, @samp{pentiumpro}, @samp{pentium2}, -@samp{pentium3}, @samp{pentium4}, @samp{k6}, @samp{k6-2}, @samp{k6-3}, -@samp{athlon}, @samp{athlon-tbird}, @samp{athlon-4}, @samp{athlon-xp}, -@samp{athlon-mp}, @samp{winchip-c6}, @samp{winchip2} and @samp{c3}. +@var{cpu-type} are: +@table @emph +@item i386 +Original Intel's i386 CPU. +@item i486 +Intel's i486 CPU. (No scheduling is implemented for this chip.) +@item i586, pentium +Intel Pentium CPU with no MMX support. +@item pentium-mmx +Intel PentiumMMX CPU based on Pentium core with MMX instruction set support. +@item i686, pentiumpro +Intel PentiumPro CPU. +@item pentium2 +Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support. +@item pentium3, pentium3m +Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set +support. +@item pentium-m +Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set +support. Used by Centrino notebooks. +@item pentium4, pentium4m +Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support. +@item prescott +Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction +set support. +@item nocona +Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE, +SSE2 and SSE3 instruction set support. +@item k6 +AMD K6 CPU with MMX instruction set support. +@item k6-2, k6-3 +Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support. +@item athlon, athlon-tbird +AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions +support. +@item athlon-4, athlon-xp, athlon-mp +Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE +instruction set support. +@item k8, opteron, athlon64, athlon-fx +AMD K8 core based CPUs with x86-64 instruction set support. (This supersets +MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.) +@item winchip-c6 +IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction +set support. +@item winchip2 +IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW! +instruction set support. +@item c3 +Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is +implemented for this chip.) +@item c3-2 +Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is +implemented for this chip.) +@end table While picking a specific @var{cpu-type} will schedule things appropriately for that particular chip, the compiler will not generate any code that does not run on the i386 without the @option{-march=@var{cpu-type}} option -being used. @samp{i586} is equivalent to @samp{pentium} and @samp{i686} -is equivalent to @samp{pentiumpro}. @samp{k6} and @samp{athlon} are the -AMD chips as opposed to the Intel ones. +being used. @item -march=@var{cpu-type} @opindex march Generate instructions for the machine type @var{cpu-type}. The choices -for @var{cpu-type} are the same as for @option{-mcpu}. Moreover, -specifying @option{-march=@var{cpu-type}} implies @option{-mcpu=@var{cpu-type}}. +for @var{cpu-type} are the same as for @option{-mtune}. Moreover, +specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}. + +@item -mcpu=@var{cpu-type} +@opindex mcpu +A deprecated synonym for @option{-mtune}. @item -m386 @itemx -m486 @@ -7866,13 +8210,13 @@ specifying @option{-march=@var{cpu-type}} implies @option{-mcpu=@var{cpu-type}}. @opindex m486 @opindex mpentium @opindex mpentiumpro -These options are synonyms for @option{-mcpu=i386}, @option{-mcpu=i486}, -@option{-mcpu=pentium}, and @option{-mcpu=pentiumpro} respectively. +These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486}, +@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively. These synonyms are deprecated. @item -mfpmath=@var{unit} @opindex march -generate floating point arithmetics for selected unit @var{unit}. the choices +Generate floating point arithmetics for selected unit @var{unit}. The choices for @var{unit} are: @table @samp @@ -7898,24 +8242,17 @@ For i387 you need to use @option{-march=@var{cpu-type}}, @option{-msse} or @option{-msse2} switches to enable SSE extensions and make this option effective. For x86-64 compiler, these extensions are enabled by default. -The resulting code should be considerably faster in majority of cases and avoid +The resulting code should be considerably faster in the majority of cases and avoid the numerical instability problems of 387 code, but may break some existing code that expects temporaries to be 80bit. -This is the default choice for x86-64 compiler. - -@item pni -Use all SSE extensions enabled by @option{-msse2} as well as the new -SSE extensions in Prescott New Intrunctions. @option{-mpni} also -enables 2 builtin functions, @code{__builtin_ia32_monitor} and -@code{__builtin_ia32_mwait}, for new intrunctions @code{monitor} and -@code{mwait}. +This is the default choice for the x86-64 compiler. @item sse,387 Attempt to utilize both instruction sets at once. This effectively double the amount of available registers and on chips with separate execution units for 387 and SSE the execution resources too. Use this option with care, as it is -still experimental, because gcc register allocator does not model separate +still experimental, because the GCC register allocator does not model separate functional units well resulting in instable performance. @end table @@ -7985,31 +8322,31 @@ and will not be binary compatible with structures in code compiled without that switch. @item -m96bit-long-double -@item -m128bit-long-double +@itemx -m128bit-long-double @opindex m96bit-long-double @opindex m128bit-long-double -These switches control the size of @code{long double} type. The i386 -application binary interface specifies the size to be 96 bits, +These switches control the size of @code{long double} type. The i386 +application binary interface specifies the size to be 96 bits, so @option{-m96bit-long-double} is the default in 32 bit mode. Modern architectures (Pentium and newer) would prefer @code{long double} -to be aligned to an 8 or 16 byte boundary. In arrays or structures -conforming to the ABI, this would not be possible. So specifying a +to be aligned to an 8 or 16 byte boundary. In arrays or structures +conforming to the ABI, this would not be possible. So specifying a @option{-m128bit-long-double} will align @code{long double} to a 16 byte boundary by padding the @code{long double} with an additional -32 bit zero. +32 bit zero. In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as its ABI specifies that @code{long double} is to be aligned on 16 byte boundary. - + Notice that neither of these options enable any extra precision over the x87 -standard of 80 bits for a @code{long double}. +standard of 80 bits for a @code{long double}. @strong{Warning:} if you override the default value for your target ABI, the -structures and arrays containing @code{long double} will change their size as -well as function calling convention for function taking @code{long double} -will be modified. Hence they will not be binary compatible with arrays or -structures in code compiled without that switch. +structures and arrays containing @code{long double} variables will change +their size as well as function calling convention for function taking +@code{long double} will be modified. Hence they will not be binary +compatible with arrays or structures in code compiled without that switch. @item -msvr3-shlib @@ -8092,8 +8429,8 @@ preferred alignment to @option{-mpreferred-stack-boundary=2}. @itemx -mno-sse @item -msse2 @itemx -mno-sse2 -@item -mpni -@itemx -mno-pni +@item -msse3 +@itemx -mno-sse3 @item -m3dnow @itemx -mno-3dnow @opindex mmmx @@ -8103,7 +8440,8 @@ preferred alignment to @option{-mpreferred-stack-boundary=2}. @opindex m3dnow @opindex mno-3dnow These switches enable or disable the use of built-in functions that allow -direct access to the MMX, SSE and 3Dnow extensions of the instruction set. +direct access to the MMX, SSE, SSE2, SSE3 and 3Dnow extensions of the +instruction set. @xref{X86 Built-in Functions}, for details of the functions enabled and disabled by these switches. @@ -8140,7 +8478,7 @@ on thread-safe exception handling must compile and link all code with the @opindex mno-align-stringops Do not align destination of inlined string operations. This switch reduces code size and improves performance in case the destination is already aligned, -but gcc don't know about it. +but GCC doesn't know about it. @item -minline-all-stringops @opindex minline-all-stringops @@ -8156,6 +8494,17 @@ avoids the instructions to save, set up and restore frame pointers and makes an extra register available in leaf functions. The option @option{-fomit-frame-pointer} removes the frame pointer for all functions which might make debugging harder. + +@item -mtls-direct-seg-refs +@itemx -mno-tls-direct-seg-refs +@opindex mtls-direct-seg-refs +Controls whether TLS variables may be accessed with offsets from the +TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit), +or whether the thread base pointer must be added. Whether or not this +is legal depends on the operating system, and whether it maps the +segment to cover the entire TLS area. + +For systems that use GNU libc, the default is on. @end table These @samp{-m} switches are supported in addition to the above @@ -8334,7 +8683,7 @@ building a shared library. It is the default when GCC is configured, explicitly or implicitly, with the GNU linker. This option does not have any affect on which ld is called, it only changes what parameters are passed to that ld. The ld that is called is determined by the -@option{--with-ld} configure option, gcc's program search path, and +@option{--with-ld} configure option, GCC's program search path, and finally by the user's @env{PATH}. The linker used by GCC can be printed using @samp{which `gcc -print-prog-name=ld`}. @@ -8346,7 +8695,7 @@ links. It is the default when GCC is configured, explicitly or implicitly, with the HP linker. This option does not have any affect on which ld is called, it only changes what parameters are passed to that ld. The ld that is called is determined by the @option{--with-ld} -configure option, gcc's program search path, and finally by the user's +configure option, GCC's program search path, and finally by the user's @env{PATH}. The linker used by GCC can be printed using @samp{which `gcc -print-prog-name=ld`}. @@ -8746,6 +9095,19 @@ heap instead of in the program's data segment. When generating code for shared libraries, @option{-fpic} implies @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}. +@item -msmall-text +@itemx -mlarge-text +@opindex msmall-text +@opindex mlarge-text +When @option{-msmall-text} is used, the compiler assumes that the +code of the entire program (or shared library) fits in 4MB, and is +thus reachable with a branch instruction. When @option{-msmall-data} +is used, the compiler can assume that all local symbols share the +same @code{$gp} value, and thus reduce the number of instructions +required for a function call from 4 to 1. + +The default is @option{-mlarge-text}. + @item -mcpu=@var{cpu_type} @opindex mcpu Set the instruction set and instruction scheduling parameters for @@ -8760,7 +9122,7 @@ Supported values for @var{cpu_type} are @table @samp @item ev4 -@item ev45 +@itemx ev45 @itemx 21064 Schedules as an EV4 and has no instruction set extensions. @@ -8782,7 +9144,7 @@ Schedules as an EV5 and supports the BWX and MAX extensions. Schedules as an EV6 and supports the BWX, FIX, and MAX extensions. @item ev67 -@item 21264a +@itemx 21264a Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions. @end table @@ -8838,7 +9200,7 @@ These @samp{-m} options are defined for the H8/300 implementations: @opindex mrelax Shorten some address references at link time, when possible; uses the linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300, -ld.info, Using ld}, for a fuller description. +ld, Using ld}, for a fuller description. @item -mh @opindex mh @@ -8884,6 +9246,9 @@ Generate code for the SH1. @opindex m2 Generate code for the SH2. +@item -m2e +Generate code for the SH2e. + @item -m3 @opindex m3 Generate code for the SH3. @@ -9029,7 +9394,7 @@ parameters for machine type @var{cpu_type}. Supported values for TMS320C40. @item -mbig-memory -@item -mbig +@itemx -mbig @itemx -msmall-memory @itemx -msmall @opindex mbig-memory @@ -9238,15 +9603,21 @@ the compiler. This setting is the default. @item -mno-app-regs @opindex mno-app-regs This option will cause r2 and r5 to be treated as fixed registers. - + +@item -mv850e1 +@opindex mv850e1 +Specify that the target processor is the V850E1. The preprocessor +constants @samp{__v850e1__} and @samp{__v850e__} will be defined if +this option is used. + @item -mv850e @opindex mv850e Specify that the target processor is the V850E. The preprocessor constant @samp{__v850e__} will be defined if this option is used. -If neither @option{-mv850} nor @option{-mv850e} are defined -then a default target processor will be chosen and the relevant -@samp{__v850*__} preprocessor constant will be defined. +If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1} +are defined then a default target processor will be chosen and the +relevant @samp{__v850*__} preprocessor constant will be defined. The preprocessor constants @samp{__v850} and @samp{__v851__} are always defined, regardless of which processor variant is the target. @@ -9254,7 +9625,7 @@ defined, regardless of which processor variant is the target. @item -mdisable-callt @opindex mdisable-callt This option will suppress generation of the CALLT instruction for the -v850e flavors of the v850 architecture. The default is +v850e and v850e1 flavors of the v850 architecture. The default is @option{-mno-disable-callt} which allows the CALLT instruction to be used. @end table @@ -9582,7 +9953,7 @@ Generate code for a big endian target. This is the default for HP-UX@. @item -mlittle-endian @opindex mlittle-endian Generate code for a little endian target. This is the default for AIX5 -and Linux. +and GNU/Linux. @item -mgnu-as @itemx -mno-gnu-as @@ -9674,6 +10045,14 @@ A fixed register is one that the register allocator can not use. This is useful when compiling kernel code. A register range is specified as two registers separated by a dash. Multiple register ranges can be specified separated by a comma. + +@item -mearly-stop-bits +@itemx -mno-early-stop-bits +@opindex mearly-stop-bits +@opindex mno-early-stop-bits +Allow stop bits to be placed earlier than immediately preceding the +instruction that triggered the stop bit. This can improve instruction +scheduling, but does not always do so. @end table @node D30V Options @@ -9743,8 +10122,9 @@ generates IEEE floating-point instructions. This is the default. @opindex mno-backchain Generate (or do not generate) code which maintains an explicit backchain within the stack frame that points to the caller's frame. -This is currently needed to allow debugging. The default is to -generate the backchain. +This may be needed to allow debugging using tools that do not understand +DWARF-2 call frame information. The default is not to generate the +backchain. @item -msmall-exec @itemx -mno-small-exec @@ -9761,12 +10141,25 @@ which does not have this limitation. @opindex m64 @opindex m31 When @option{-m31} is specified, generate code compliant to the -Linux for S/390 ABI@. When @option{-m64} is specified, generate -code compliant to the Linux for zSeries ABI@. This allows GCC in +GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate +code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in particular to generate 64-bit instructions. For the @samp{s390} targets, the default is @option{-m31}, while the @samp{s390x} targets default to @option{-m64}. +@item -mzarch +@itemx -mesa +@opindex mzarch +@opindex mesa +When @option{-mzarch} is specified, generate code using the +instructions available on z/Architecture. +When @option{-mesa} is specified, generate code using the +instructions available on ESA/390. Note that @option{-mesa} is +not possible with @option{-m64}. +When generating code compliant to the GNU/Linux for S/390 ABI, +the default is @option{-mesa}. When generating code compliant +to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}. + @item -mmvcle @itemx -mno-mvcle @opindex mmvcle @@ -9782,6 +10175,29 @@ use a @code{mvc} loop instead. This is the default. Print (or do not print) additional debug information when compiling. The default is to not print debug information. +@item -march=@var{cpu-type} +@opindex march +Generate code that will run on @var{cpu-type}, which is the name of a system +representing a certain processor type. Possible values for +@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}. +When generating code using the instructions available on z/Architecture, +the default is @option{-march=z900}. Otherwise, the default is +@option{-march=g5}. + +@item -mtune=@var{cpu-type} +@opindex mtune +Tune to @var{cpu-type} everything applicable about the generated code, +except for the ABI and the set of available instructions. +The list of @var{cpu-type} values is the same as for @option{-march}. +The default is the value used for @option{-march}. + +@item -mfused-madd +@itemx -mno-fused-madd +@opindex mfused-madd +@opindex mno-fused-madd +Generate code that uses (does not use) the floating point multiply and +accumulate instructions. These instructions are generated by default if +hardware floating point is used. @end table @node CRIS Options @@ -9825,6 +10241,13 @@ program should be set to @var{n} bytes. The options @option{-metrax4} and @option{-metrax100} are synonyms for @option{-march=v3} and @option{-march=v8} respectively. +@item -mmul-bug-workaround +@itemx -mno-mul-bug-workaround +@opindex mmul-bug-workaround +@opindex mno-mul-bug-workaround +Work around a bug in the @code{muls} and @code{mulu} instructions for CPU +models where it applies. This option is active by default. + @item -mpdebug @opindex mpdebug Enable CRIS-specific verbose debug-related information in the assembly @@ -10071,7 +10494,7 @@ Use 32-bit @code{int}. Use 64-bit @code{float}. This is the default. @item -mfloat32 -@item -mno-float64 +@itemx -mno-float64 @opindex mfloat32 @opindex mno-float64 Use 32-bit @code{float}. @@ -10355,100 +10778,19 @@ Select the processor type for which to generate code. Possible values are @subsection Xtensa Options @cindex Xtensa Options -The Xtensa architecture is designed to support many different -configurations. The compiler's default options can be set to match a -particular Xtensa configuration by copying a configuration file into the -GCC sources when building GCC@. The options below may be used to -override the default options. +These options are supported for Xtensa targets: @table @gcctabopt -@item -mbig-endian -@itemx -mlittle-endian -@opindex mbig-endian -@opindex mlittle-endian -Specify big-endian or little-endian byte ordering for the target Xtensa -processor. - -@item -mdensity -@itemx -mno-density -@opindex mdensity -@opindex mno-density -Enable or disable use of the optional Xtensa code density instructions. - -@item -mmac16 -@itemx -mno-mac16 -@opindex mmac16 -@opindex mno-mac16 -Enable or disable use of the Xtensa MAC16 option. When enabled, GCC -will generate MAC16 instructions from standard C code, with the -limitation that it will use neither the MR register file nor any -instruction that operates on the MR registers. When this option is -disabled, GCC will translate 16-bit multiply/accumulate operations to a -combination of core instructions and library calls, depending on whether -any other multiplier options are enabled. - -@item -mmul16 -@itemx -mno-mul16 -@opindex mmul16 -@opindex mno-mul16 -Enable or disable use of the 16-bit integer multiplier option. When -enabled, the compiler will generate 16-bit multiply instructions for -multiplications of 16 bits or smaller in standard C code. When this -option is disabled, the compiler will either use 32-bit multiply or -MAC16 instructions if they are available or generate library calls to -perform the multiply operations using shifts and adds. - -@item -mmul32 -@itemx -mno-mul32 -@opindex mmul32 -@opindex mno-mul32 -Enable or disable use of the 32-bit integer multiplier option. When -enabled, the compiler will generate 32-bit multiply instructions for -multiplications of 32 bits or smaller in standard C code. When this -option is disabled, the compiler will generate library calls to perform -the multiply operations using either shifts and adds or 16-bit multiply -instructions if they are available. - -@item -mnsa -@itemx -mno-nsa -@opindex mnsa -@opindex mno-nsa -Enable or disable use of the optional normalization shift amount -(@code{NSA}) instructions to implement the built-in @code{ffs} function. - -@item -mminmax -@itemx -mno-minmax -@opindex mminmax -@opindex mno-minmax -Enable or disable use of the optional minimum and maximum value -instructions. - -@item -msext -@itemx -mno-sext -@opindex msext -@opindex mno-sext -Enable or disable use of the optional sign extend (@code{SEXT}) -instruction. - -@item -mbooleans -@itemx -mno-booleans -@opindex mbooleans -@opindex mno-booleans -Enable or disable support for the boolean register file used by Xtensa -coprocessors. This is not typically useful by itself but may be -required for other options that make use of the boolean registers (e.g., -the floating-point option). - -@item -mhard-float -@itemx -msoft-float -@opindex mhard-float -@opindex msoft-float -Enable or disable use of the floating-point option. When enabled, GCC -generates floating-point instructions for 32-bit @code{float} -operations. When this option is disabled, GCC generates library calls -to emulate 32-bit floating-point operations using integer instructions. -Regardless of this option, 64-bit @code{double} operations are always -emulated with calls to library functions. +@item -mconst16 +@itemx -mno-const16 +@opindex mconst16 +@opindex mno-const16 +Enable or disable use of @code{CONST16} instructions for loading +constant values. The @code{CONST16} instruction is currently not a +standard option from Tensilica. When enabled, @code{CONST16} +instructions are always used in place of the standard @code{L32R} +instructions. The use of @code{CONST16} is enabled by default only if +the @code{L32R} instruction is not available. @item -mfused-madd @itemx -mno-fused-madd @@ -10467,15 +10809,6 @@ add/subtract instructions also ensures that the program output is not sensitive to the compiler's ability to combine multiply and add/subtract operations. -@item -mserialize-volatile -@itemx -mno-serialize-volatile -@opindex mserialize-volatile -@opindex mno-serialize-volatile -When this option is enabled, GCC inserts @code{MEMW} instructions before -@code{volatile} memory references to guarantee sequential consistency. -The default is @option{-mserialize-volatile}. Use -@option{-mno-serialize-volatile} to omit the @code{MEMW} instructions. - @item -mtext-section-literals @itemx -mno-text-section-literals @opindex mtext-section-literals @@ -10552,6 +10885,14 @@ this option defaults to true and false respectively. This option generates traps for signed overflow on addition, subtraction, multiplication operations. +@item -fwrapv +@opindex fwrapv +This option instructs the compiler to assume that signed arithmetic +overflow of addition, subtraction and multiplication wraps around +using twos-complement representation. This flag enables some optimizations +and disables other. This option is enabled by default for the Java +front-end, as required by the Java language specification. + @item -fexceptions @opindex fexceptions Enable exception handling. Generates extra code needed to propagate @@ -10674,17 +11015,6 @@ program will work on other systems which always work this way. @opindex fno-ident Ignore the @samp{#ident} directive. -@item -fno-gnu-linker -@opindex fno-gnu-linker -Do not output global initializations (such as C++ constructors and -destructors) in the form used by the GNU linker (on systems where the GNU -linker is the standard method of handling them). Use this option when -you want to use a non-GNU linker, which also requires using the -@command{collect2} program to make sure the system linker includes -constructors and destructors. (@command{collect2} is included in the GCC -distribution.) For systems which @emph{must} use @command{collect2}, the -compiler driver @command{gcc} is configured to do this automatically. - @item -finhibit-size-directive @opindex finhibit-size-directive Don't output a @code{.size} assembler directive, or anything else that @@ -10704,20 +11034,6 @@ debugging the compiler itself). extra information to be omitted and is useful when comparing two assembler files. -@item -fvolatile -@opindex fvolatile -Consider all memory references through pointers to be volatile. - -@item -fvolatile-global -@opindex fvolatile-global -Consider all memory references to extern and global data items to -be volatile. GCC does not consider static data items to be volatile -because of this switch. - -@item -fvolatile-static -@opindex fvolatile-static -Consider all memory references to static data to be volatile. - @item -fpic @opindex fpic @cindex global offset table @@ -10730,7 +11046,7 @@ loader is not part of GCC; it is part of the operating system). If the GOT size for the linked executable exceeds a machine-specific maximum size, you get an error message from the linker indicating that @option{-fpic} does not work; in that case, recompile with @option{-fPIC} -instead. (These maximums are 16k on the m88k, 8k on the SPARC, and 32k +instead. (These maximums are 8k on the SPARC and 32k on the m68k and RS/6000. The 386 has no such limit.) Position-independent code requires special support, and therefore works @@ -10742,12 +11058,21 @@ position-independent. @opindex fPIC If supported for the target machine, emit position-independent code, suitable for dynamic linking and avoiding any limit on the size of the -global offset table. This option makes a difference on the m68k, m88k, +global offset table. This option makes a difference on the m68k and the SPARC. Position-independent code requires special support, and therefore works only on certain machines. +@item -fpie +@itemx -fPIE +@opindex fpie +@opindex fPIE +These options are similar to @option{-fpic} and @option{-fPIC}, but +generated position independent code can be only linked into executables. +Usually these options are used when @option{-pie} GCC option will be +used during linking. + @item -ffixed-@var{reg} @opindex ffixed Treat the register named @var{reg} as a fixed register; generated code @@ -10811,26 +11136,18 @@ function and its call site. (On some platforms, function, so the call site information may not be available to the profiling functions otherwise.) -@example +@smallexample void __cyg_profile_func_enter (void *this_fn, void *call_site); void __cyg_profile_func_exit (void *this_fn, void *call_site); -@end example +@end smallexample The first argument is the address of the start of the current function, which may be looked up exactly in the symbol table. -This instrumentation is also done for functions expanded inline in other -functions. The profiling calls will indicate where, conceptually, the -inline function is entered and exited. This means that addressable -versions of such functions must be available. If all your uses of a -function are expanded inline, this may mean an additional expansion of -code size. If you use @samp{extern inline} in your C code, an -addressable version of such functions must be provided. (This is -normally the case anyways, but if you get lucky and the optimizer always -expands the functions inline, you might have gotten away without -providing static copies.) +This currently disables function inlining. This restriction is +expected to be removed in future releases. A function may be given the attribute @code{no_instrument_function}, in which case this instrumentation will not be done. This can be used, for @@ -10992,7 +11309,7 @@ If GCC cannot find the subprogram using the specified prefix, it tries looking in the usual places for the subprogram. The default value of @env{GCC_EXEC_PREFIX} is -@file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value +@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value of @code{prefix} when you ran the @file{configure} script. Other prefixes specified with @option{-B} take precedence over this prefix. @@ -11002,7 +11319,7 @@ used for linking. In addition, the prefix is used in an unusual way in finding the directories to search for header files. For each of the standard -directories whose name normally begins with @samp{/usr/local/lib/gcc-lib} +directories whose name normally begins with @samp{/usr/local/lib/gcc} (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries replacing that beginning with the specified prefix to produce an alternate directory name. Thus, with @option{-Bfoo/}, GCC will search @@ -11058,6 +11375,111 @@ preprocessor. @c man end +@node Precompiled Headers +@section Using Precompiled Headers +@cindex precompiled headers +@cindex speed of compilation + +Often large projects have many header files that are included in every +source file. The time the compiler takes to process these header files +over and over again can account for nearly all of the time required to +build the project. To make builds faster, GCC allows users to +`precompile' a header file; then, if builds can use the precompiled +header file they will be much faster. + +@strong{Caution:} There are a few known situations where GCC will +crash when trying to use a precompiled header. If you have trouble +with a precompiled header, you should remove the precompiled header +and compile without it. In addition, please use GCC's on-line +defect-tracking system to report any problems you encounter with +precompiled headers. @xref{Bugs}. + +To create a precompiled header file, simply compile it as you would any +other file, if necessary using the @option{-x} option to make the driver +treat it as a C or C++ header file. You will probably want to use a +tool like @command{make} to keep the precompiled header up-to-date when +the headers it contains change. + +A precompiled header file will be searched for when @code{#include} is +seen in the compilation. As it searches for the included file +(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the +compiler looks for a precompiled header in each directory just before it +looks for the include file in that directory. The name searched for is +the name specified in the @code{#include} with @samp{.gch} appended. If +the precompiled header file can't be used, it is ignored. + +For instance, if you have @code{#include "all.h"}, and you have +@file{all.h.gch} in the same directory as @file{all.h}, then the +precompiled header file will be used if possible, and the original +header will be used otherwise. + +Alternatively, you might decide to put the precompiled header file in a +directory and use @option{-I} to ensure that directory is searched +before (or instead of) the directory containing the original header. +Then, if you want to check that the precompiled header file is always +used, you can put a file of the same name as the original header in this +directory containing an @code{#error} command. + +This also works with @option{-include}. So yet another way to use +precompiled headers, good for projects not designed with precompiled +header files in mind, is to simply take most of the header files used by +a project, include them from another header file, precompile that header +file, and @option{-include} the precompiled header. If the header files +have guards against multiple inclusion, they will be skipped because +they've already been included (in the precompiled header). + +If you need to precompile the same header file for different +languages, targets, or compiler options, you can instead make a +@emph{directory} named like @file{all.h.gch}, and put each precompiled +header in the directory. (It doesn't matter what you call the files +in the directory, every precompiled header in the directory will be +considered.) The first precompiled header encountered in the +directory that is valid for this compilation will be used; they're +searched in no particular order. + +There are many other possibilities, limited only by your imagination, +good sense, and the constraints of your build system. + +A precompiled header file can be used only when these conditions apply: + +@itemize +@item +Only one precompiled header can be used in a particular compilation. +@item +A precompiled header can't be used once the first C token is seen. You +can have preprocessor directives before a precompiled header; you can +even include a precompiled header from inside another header, so long as +there are no C tokens before the @code{#include}. +@item +The precompiled header file must be produced for the same language as +the current compilation. You can't use a C precompiled header for a C++ +compilation. +@item +The precompiled header file must be produced by the same compiler +version and configuration as the current compilation is using. +The easiest way to guarantee this is to use the same compiler binary +for creating and using precompiled headers. +@item +Any macros defined before the precompiled header (including with +@option{-D}) must either be defined in the same way as when the +precompiled header was generated, or must not affect the precompiled +header, which usually means that the they don't appear in the +precompiled header at all. +@item +Certain command-line options must be defined in the same way as when the +precompiled header was generated. At present, it's not clear which +options are safe to change and which are not; the safest choice is to +use exactly the same options when generating and using the precompiled +header. +@end itemize + +For all of these but the last, the compiler will automatically ignore +the precompiled header if the conditions aren't met. For the last item, +some option changes will cause the precompiled header to be rejected, +but not all incompatible option combinations have yet been found. If +you find a new incompatible combination, please consider filing a bug +report, see @ref{Bugs}. + @node Running Protoize @section Running Protoize @@ -11198,10 +11620,10 @@ appropriate options and the option @option{-aux-info}. Then run the existing @samp{.X} file because it is newer than the source file. For example: -@example +@smallexample gcc -Dfoo=bar file1.c -aux-info file1.X protoize *.c -@end example +@end smallexample @noindent You need to include the special files along with the rest in the diff --git a/contrib/gcc/doc/libgcc.texi b/contrib/gcc/doc/libgcc.texi new file mode 100644 index 0000000..41e214e --- /dev/null +++ b/contrib/gcc/doc/libgcc.texi @@ -0,0 +1,484 @@ +@c Copyright (C) 2003, 2004 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. +@c Contributed by Aldy Hernandez <aldy@quesejoda.com> + +@node Libgcc +@chapter The GCC low-level runtime library + +GCC provides a low-level runtime library, @file{libgcc.a} or +@file{libgcc_s.so.1} on some platforms. GCC generates calls to +routines in this library automatically, whenever it needs to perform +some operation that is too complicated to emit inline code for. + +Most of the routines in @code{libgcc} handle arithmetic operations +that the target processor cannot perform directly. This includes +integer multiply and divide on some machines, and all floating-point +operations on other machines. @code{libgcc} also includes routines +for exception handling, and a handful of miscellaneous operations. + +Some of these routines can be defined in mostly machine-independent C. +Others must be hand-written in assembly language for each processor +that needs them. + +GCC will also generate calls to C library routines, such as +@code{memcpy} and @code{memset}, in some cases. The set of routines +that GCC may possibly use is documented in @ref{Other +Builtins,,,gcc, Using the GNU Compiler Collection (GCC)}. + +These routines take arguments and return values of a specific machine +mode, not a specific C type. @xref{Machine Modes}, for an explanation +of this concept. For illustrative purposes, in this chapter the +floating point type @code{float} is assumed to correspond to @code{SFmode}; +@code{double} to @code{DFmode}; and @code{@w{long double}} to both +@code{TFmode} and @code{XFmode}. Similarly, the integer types @code{int} +and @code{@w{unsigned int}} correspond to @code{SImode}; @code{long} and +@code{@w{unsigned long}} to @code{DImode}; and @code{@w{long long}} and +@code{@w{unsigned long long}} to @code{TImode}. + +@menu +* Integer library routines:: +* Soft float library routines:: +* Exception handling routines:: +* Miscellaneous routines:: +@end menu + +@node Integer library routines +@section Routines for integer arithmetic + +The integer arithmetic routines are used on platforms that don't provide +hardware support for arithmetic operations on some modes. + +@subsection Arithmetic functions + +@deftypefn {Runtime Function} int __ashlsi3 (int @var{a}, int @var{b}) +@deftypefnx {Runtime Function} long __ashldi3 (long @var{a}, int @var{b}) +@deftypefnx {Runtime Function} {long long} __ashlti3 (long long @var{a}, int @var{b}) +These functions return the result of shifting @var{a} left by @var{b} bits. +@end deftypefn + +@deftypefn {Runtime Function} int __ashrsi3 (int @var{a}, int @var{b}) +@deftypefnx {Runtime Function} long __ashrdi3 (long @var{a}, int @var{b}) +@deftypefnx {Runtime Function} {long long} __ashrti3 (long long @var{a}, int @var{b}) +These functions return the result of arithmetically shifting @var{a} right +by @var{b} bits. +@end deftypefn + +@deftypefn {Runtime Function} int __divsi3 (int @var{a}, int @var{b}) +@deftypefnx {Runtime Function} long __divdi3 (long @var{a}, long @var{b}) +@deftypefnx {Runtime Function} {long long} __divti3 (long long @var{a}, long long @var{b}) +These functions return the quotient of the signed division of @var{a} and +@var{b}. +@end deftypefn + +@deftypefn {Runtime Function} int __lshrsi3 (int @var{a}, int @var{b}) +@deftypefnx {Runtime Function} long __lshrdi3 (long @var{a}, int @var{b}) +@deftypefnx {Runtime Function} {long long} __lshrti3 (long long @var{a}, int @var{b}) +These functions return the result of logically shifting @var{a} right by +@var{b} bits. +@end deftypefn + +@deftypefn {Runtime Function} int __modsi3 (int @var{a}, int @var{b}) +@deftypefnx {Runtime Function} long __moddi3 (long @var{a}, long @var{b}) +@deftypefnx {Runtime Function} {long long} __modti3 (long long @var{a}, long long @var{b}) +These functions return the remainder of the signed division of @var{a} +and @var{b}. +@end deftypefn + +@deftypefn {Runtime Function} int __mulsi3 (int @var{a}, int @var{b}) +@deftypefnx {Runtime Function} long __muldi3 (long @var{a}, long @var{b}) +@deftypefnx {Runtime Function} {long long} __multi3 (long long @var{a}, long long @var{b}) +These functions return the product of @var{a} and @var{b}. +@end deftypefn + +@deftypefn {Runtime Function} long __negdi2 (long @var{a}) +@deftypefnx {Runtime Function} {long long} __negti2 (long long @var{a}) +These functions return the negation of @var{a}. +@end deftypefn + +@deftypefn {Runtime Function} {unsigned int} __udivsi3 (unsigned int @var{a}, unsigned int @var{b}) +@deftypefnx {Runtime Function} {unsigned long} __udivdi3 (unsigned long @var{a}, unsigned long @var{b}) +@deftypefnx {Runtime Function} {unsigned long long} __udivti3 (unsigned long long @var{a}, unsigned long long @var{b}) +These functions return the quotient of the unsigned division of @var{a} +and @var{b}. +@end deftypefn + +@deftypefn {Runtime Function} {unsigned long} __udivmoddi3 (unsigned long @var{a}, unsigned long @var{b}, unsigned long *@var{c}) +@deftypefnx {Runtime Function} {unsigned long long} __udivti3 (unsigned long long @var{a}, unsigned long long @var{b}, unsigned long long *@var{c}) +These functions calculate both the quotient and remainder of the unsigned +division of @var{a} and @var{b}. The return value is the quotient, and +the remainder is placed in variable pointed to by @var{c}. +@end deftypefn + +@deftypefn {Runtime Function} {unsigned int} __umodsi3 (unsigned int @var{a}, unsigned int @var{b}) +@deftypefnx {Runtime Function} {unsigned long} __umoddi3 (unsigned long @var{a}, unsigned long @var{b}) +@deftypefnx {Runtime Function} {unsigned long long} __umodti3 (unsigned long long @var{a}, unsigned long long @var{b}) +These functions return the remainder of the unsigned division of @var{a} +and @var{b}. +@end deftypefn + +@subsection Comparison functions + +The following functions implement integral comparisons. These functions +implement a low-level compare, upon which the higher level comparison +operators (such as less than and greater than or equal to) can be +constructed. The returned values lie in the range zero to two, to allow +the high-level operators to be implemented by testing the returned +result using either signed or unsigned comparison. + +@deftypefn {Runtime Function} int __cmpdi2 (long @var{a}, long @var{b}) +@deftypefnx {Runtime Function} int __cmpti2 (long long @var{a}, long long @var{b}) +These functions perform a signed comparison of @var{a} and @var{b}. If +@var{a} is less than @var{b}, they return 0; if @var{a} is greater than +@var{b}, they return 2; and if @var{a} and @var{b} are equal they return 1. +@end deftypefn + +@deftypefn {Runtime Function} int __ucmpdi2 (unsigned long @var{a}, unsigned long @var{b}) +@deftypefnx {Runtime Function} int __ucmpti2 (unsigned long long @var{a}, unsigned long long @var{b}) +These functions perform an unsigned comparison of @var{a} and @var{b}. +If @var{a} is less than @var{b}, they return 0; if @var{a} is greater than +@var{b}, they return 2; and if @var{a} and @var{b} are equal they return 1. +@end deftypefn + +@subsection Trapping arithmetic functions + +The following functions implement trapping arithmetic. These functions +call the libc function @code{abort} upon signed arithmetic overflow. + +@deftypefn {Runtime Function} int __absvsi2 (int @var{a}) +@deftypefnx {Runtime Function} long __absvdi2 (long @var{a}) +These functions return the absolute value of @var{a}. +@end deftypefn + +@deftypefn {Runtime Function} int __addvsi3 (int @var{a}, int @var{b}) +@deftypefnx {Runtime Function} long __addvdi3 (long @var{a}, long @var{b}) +These functions return the sum of @var{a} and @var{b}; that is +@code{@var{a} + @var{b}}. +@end deftypefn + +@deftypefn {Runtime Function} int __mulvsi3 (int @var{a}, int @var{b}) +@deftypefnx {Runtime Function} long __mulvdi3 (long @var{a}, long @var{b}) +The functions return the product of @var{a} and @var{b}; that is +@code{@var{a} * @var{b}}. +@end deftypefn + +@deftypefn {Runtime Function} int __negvsi2 (int @var{a}) +@deftypefnx {Runtime Function} long __negvdi2 (long @var{a}) +These functions return the negation of @var{a}; that is @code{-@var{a}}. +@end deftypefn + +@deftypefn {Runtime Function} int __subvsi3 (int @var{a}, int @var{b}) +@deftypefnx {Runtime Function} long __subvdi3 (long @var{a}, long @var{b}) +These functions return the difference between @var{b} and @var{a}; +that is @code{@var{a} - @var{b}}. +@end deftypefn + +@subsection Bit operations + +@deftypefn {Runtime Function} int __clzsi2 (int @var{a}) +@deftypefnx {Runtime Function} int __clzdi2 (long @var{a}) +@deftypefnx {Runtime Function} int __clzti2 (long long @var{a}) +These functions return the number of leading 0-bits in @var{a}, starting +at the most significant bit position. If @var{a} is zero, the result is +undefined. +@end deftypefn + +@deftypefn {Runtime Function} int __ctzsi2 (int @var{a}) +@deftypefnx {Runtime Function} int __ctzdi2 (long @var{a}) +@deftypefnx {Runtime Function} int __ctzti2 (long long @var{a}) +These functions return the number of trailing 0-bits in @var{a}, starting +at the least significant bit position. If @var{a} is zero, the result is +undefined. +@end deftypefn + +@deftypefn {Runtime Function} int __ffsdi2 (long @var{a}) +@deftypefnx {Runtime Function} int __ffsti2 (long long @var{a}) +These functions return the index of the least significant 1-bit in @var{a}, +or the value zero if @var{a} is zero. The least significant bit is index +one. +@end deftypefn + +@deftypefn {Runtime Function} int __paritysi2 (int @var{a}) +@deftypefnx {Runtime Function} int __paritydi2 (long @var{a}) +@deftypefnx {Runtime Function} int __parityti2 (long long @var{a}) +These functions return the value zero if the number of bits set in +@var{a} is even, and the value one otherwise. +@end deftypefn + +@deftypefn {Runtime Function} int __popcountsi2 (int @var{a}) +@deftypefnx {Runtime Function} int __popcountdi2 (long @var{a}) +@deftypefnx {Runtime Function} int __popcountti2 (long long @var{a}) +These functions return the number of bits set in @var{a}. +@end deftypefn + +@node Soft float library routines +@section Routines for floating point emulation +@cindex soft float library +@cindex arithmetic library +@cindex math library +@opindex msoft-float + +The software floating point library is used on machines which do not +have hardware support for floating point. It is also used whenever +@option{-msoft-float} is used to disable generation of floating point +instructions. (Not all targets support this switch.) + +For compatibility with other compilers, the floating point emulation +routines can be renamed with the @code{DECLARE_LIBRARY_RENAMES} macro +(@pxref{Library Calls}). In this section, the default names are used. + +Presently the library does not support @code{XFmode}, which is used +for @code{long double} on some architectures. + +@subsection Arithmetic functions + +@deftypefn {Runtime Function} float __addsf3 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} double __adddf3 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} {long double} __addtf3 (long double @var{a}, long double @var{b}) +@deftypefnx {Runtime Function} {long double} __addxf3 (long double @var{a}, long double @var{b}) +These functions return the sum of @var{a} and @var{b}. +@end deftypefn + +@deftypefn {Runtime Function} float __subsf3 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} double __subdf3 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} {long double} __subtf3 (long double @var{a}, long double @var{b}) +@deftypefnx {Runtime Function} {long double} __subxf3 (long double @var{a}, long double @var{b}) +These functions return the difference between @var{b} and @var{a}; +that is, @w{@math{@var{a} - @var{b}}}. +@end deftypefn + +@deftypefn {Runtime Function} float __mulsf3 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} double __muldf3 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} {long double} __multf3 (long double @var{a}, long double @var{b}) +@deftypefnx {Runtime Function} {long double} __mulxf3 (long double @var{a}, long double @var{b}) +These functions return the product of @var{a} and @var{b}. +@end deftypefn + +@deftypefn {Runtime Function} float __divsf3 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} double __divdf3 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} {long double} __divtf3 (long double @var{a}, long double @var{b}) +@deftypefnx {Runtime Function} {long double} __divxf3 (long double @var{a}, long double @var{b}) +These functions return the quotient of @var{a} and @var{b}; that is, +@w{@math{@var{a} / @var{b}}}. +@end deftypefn + +@deftypefn {Runtime Function} float __negsf2 (float @var{a}) +@deftypefnx {Runtime Function} double __negdf2 (double @var{a}) +@deftypefnx {Runtime Function} {long double} __negtf2 (long double @var{a}) +@deftypefnx {Runtime Function} {long double} __negxf2 (long double @var{a}) +These functions return the negation of @var{a}. They simply flip the +sign bit, so they can produce negative zero and negative NaN. +@end deftypefn + +@subsection Conversion functions + +@deftypefn {Runtime Function} double __extendsfdf2 (float @var{a}) +@deftypefnx {Runtime Function} {long double} __extendsftf2 (float @var{a}) +@deftypefnx {Runtime Function} {long double} __extendsfxf2 (float @var{a}) +@deftypefnx {Runtime Function} {long double} __extenddftf2 (double @var{a}) +@deftypefnx {Runtime Function} {long double} __extenddfxf2 (double @var{a}) +These functions extend @var{a} to the wider mode of their return +type. +@end deftypefn + +@deftypefn {Runtime Function} double __truncxfdf2 (long double @var{a}) +@deftypefnx {Runtime Function} double __trunctfdf2 (long double @var{a}) +@deftypefnx {Runtime Function} float __truncxfsf2 (long double @var{a}) +@deftypefnx {Runtime Function} float __trunctfsf2 (long double @var{a}) +@deftypefnx {Runtime Function} float __truncdfsf2 (double @var{a}) +These functions truncate @var{a} to the narrower mode of their return +type, rounding toward zero. +@end deftypefn + +@deftypefn {Runtime Function} int __fixsfsi (float @var{a}) +@deftypefnx {Runtime Function} int __fixdfsi (double @var{a}) +@deftypefnx {Runtime Function} int __fixtfsi (long double @var{a}) +@deftypefnx {Runtime Function} int __fixxfsi (long double @var{a}) +These functions convert @var{a} to a signed integer, rounding toward zero. +@end deftypefn + +@deftypefn {Runtime Function} long __fixsfdi (float @var{a}) +@deftypefnx {Runtime Function} long __fixdfdi (double @var{a}) +@deftypefnx {Runtime Function} long __fixtfdi (long double @var{a}) +@deftypefnx {Runtime Function} long __fixxfdi (long double @var{a}) +These functions convert @var{a} to a signed long, rounding toward zero. +@end deftypefn + +@deftypefn {Runtime Function} {long long} __fixsfti (float @var{a}) +@deftypefnx {Runtime Function} {long long} __fixdfti (double @var{a}) +@deftypefnx {Runtime Function} {long long} __fixtfti (long double @var{a}) +@deftypefnx {Runtime Function} {long long} __fixxfti (long double @var{a}) +These functions convert @var{a} to a signed long long, rounding toward zero. +@end deftypefn + +@deftypefn {Runtime Function} {unsigned int} __fixunssfsi (float @var{a}) +@deftypefnx {Runtime Function} {unsigned int} __fixunsdfsi (double @var{a}) +@deftypefnx {Runtime Function} {unsigned int} __fixunstfsi (long double @var{a}) +@deftypefnx {Runtime Function} {unsigned int} __fixunsxfsi (long double @var{a}) +These functions convert @var{a} to an unsigned integer, rounding +toward zero. Negative values all become zero. +@end deftypefn + +@deftypefn {Runtime Function} {unsigned long} __fixunssfdi (float @var{a}) +@deftypefnx {Runtime Function} {unsigned long} __fixunsdfdi (double @var{a}) +@deftypefnx {Runtime Function} {unsigned long} __fixunstfdi (long double @var{a}) +@deftypefnx {Runtime Function} {unsigned long} __fixunsxfdi (long double @var{a}) +These functions convert @var{a} to an unsigned long, rounding +toward zero. Negative values all become zero. +@end deftypefn + +@deftypefn {Runtime Function} {unsigned long long} __fixunssfti (float @var{a}) +@deftypefnx {Runtime Function} {unsigned long long} __fixunsdfti (double @var{a}) +@deftypefnx {Runtime Function} {unsigned long long} __fixunstfti (long double @var{a}) +@deftypefnx {Runtime Function} {unsigned long long} __fixunsxfti (long double @var{a}) +These functions convert @var{a} to an unsigned long long, rounding +toward zero. Negative values all become zero. +@end deftypefn + +@deftypefn {Runtime Function} float __floatsisf (int @var{i}) +@deftypefnx {Runtime Function} double __floatsidf (int @var{i}) +@deftypefnx {Runtime Function} {long double} __floatsitf (int @var{i}) +@deftypefnx {Runtime Function} {long double} __floatsixf (int @var{i}) +These functions convert @var{i}, a signed integer, to floating point. +@end deftypefn + +@deftypefn {Runtime Function} float __floatdisf (long @var{i}) +@deftypefnx {Runtime Function} double __floatdidf (long @var{i}) +@deftypefnx {Runtime Function} {long double} __floatditf (long @var{i}) +@deftypefnx {Runtime Function} {long double} __floatdixf (long @var{i}) +These functions convert @var{i}, a signed long, to floating point. +@end deftypefn + +@deftypefn {Runtime Function} float __floattisf (long long @var{i}) +@deftypefnx {Runtime Function} double __floattidf (long long @var{i}) +@deftypefnx {Runtime Function} {long double} __floattitf (long long @var{i}) +@deftypefnx {Runtime Function} {long double} __floattixf (long long @var{i}) +These functions convert @var{i}, a signed long long, to floating point. +@end deftypefn + +@subsection Comparison functions + +There are two sets of basic comparison functions. + +@deftypefn {Runtime Function} int __cmpsf2 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} int __cmpdf2 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} int __cmptf2 (long double @var{a}, long double @var{b}) +These functions calculate @math{a <=> b}. That is, if @var{a} is less +than @var{b}, they return -1; if @var{a} is greater than @var{b}, they +return 1; and if @var{a} and @var{b} are equal they return 0. If +either argument is NaN they return 1, but you should not rely on this; +if NaN is a possibility, use one of the higher-level comparison +functions. +@end deftypefn + +@deftypefn {Runtime Function} int __unordsf2 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} int __unorddf2 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} int __unordtf2 (long double @var{a}, long double @var{b}) +These functions return a nonzero value if either argument is NaN, otherwise 0. +@end deftypefn + +There is also a complete group of higher level functions which +correspond directly to comparison operators. They implement the ISO C +semantics for floating-point comparisons, taking NaN into account. +Pay careful attention to the return values defined for each set. +Under the hood, all of these routines are implemented as + +@smallexample + if (__unord@var{X}f2 (a, b)) + return @var{E}; + return __cmp@var{X}f2 (a, b); +@end smallexample + +@noindent +where @var{E} is a constant chosen to give the proper behavior for +NaN. Thus, the meaning of the return value is different for each set. +Do not rely on this implementation; only the semantics documented +below are guaranteed. + +@deftypefn {Runtime Function} int __eqsf2 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} int __eqdf2 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} int __eqtf2 (long double @var{a}, long double @var{b}) +These functions return zero if neither argument is NaN, and @var{a} and +@var{b} are equal. +@end deftypefn + +@deftypefn {Runtime Function} int __nesf2 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} int __nedf2 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} int __netf2 (long double @var{a}, long double @var{b}) +These functions return a nonzero value if either argument is NaN, or +if @var{a} and @var{b} are unequal. +@end deftypefn + +@deftypefn {Runtime Function} int __gesf2 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} int __gedf2 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} int __getf2 (long double @var{a}, long double @var{b}) +These functions return a value greater than or equal to zero if +neither argument is NaN, and @var{a} is greater than or equal to +@var{b}. +@end deftypefn + +@deftypefn {Runtime Function} int __ltsf2 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} int __ltdf2 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} int __lttf2 (long double @var{a}, long double @var{b}) +These functions return a value less than zero if neither argument is +NaN, and @var{a} is strictly less than @var{b}. +@end deftypefn + +@deftypefn {Runtime Function} int __lesf2 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} int __ledf2 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} int __letf2 (long double @var{a}, long double @var{b}) +These functions return a value less than or equal to zero if neither +argument is NaN, and @var{a} is less than or equal to @var{b}. +@end deftypefn + +@deftypefn {Runtime Function} int __gtsf2 (float @var{a}, float @var{b}) +@deftypefnx {Runtime Function} int __gtdf2 (double @var{a}, double @var{b}) +@deftypefnx {Runtime Function} int __gttf2 (long double @var{a}, long double @var{b}) +These functions return a value greater than zero if neither argument +is NaN, and @var{a} is strictly greater than @var{b}. +@end deftypefn + +@node Exception handling routines +@section Language-independent routines for exception handling + +document me! + +@smallexample + _Unwind_DeleteException + _Unwind_Find_FDE + _Unwind_ForcedUnwind + _Unwind_GetGR + _Unwind_GetIP + _Unwind_GetLanguageSpecificData + _Unwind_GetRegionStart + _Unwind_GetTextRelBase + _Unwind_GetDataRelBase + _Unwind_RaiseException + _Unwind_Resume + _Unwind_SetGR + _Unwind_SetIP + _Unwind_FindEnclosingFunction + _Unwind_SjLj_Register + _Unwind_SjLj_Unregister + _Unwind_SjLj_RaiseException + _Unwind_SjLj_ForcedUnwind + _Unwind_SjLj_Resume + __deregister_frame + __deregister_frame_info + __deregister_frame_info_bases + __register_frame + __register_frame_info + __register_frame_info_bases + __register_frame_info_table + __register_frame_info_table_bases + __register_frame_table +@end smallexample + +@node Miscellaneous routines +@section Miscellaneous runtime library routines + +@subsection Cache control functions +@deftypefn {Runtime Function} void __clear_cache (char *@var{beg}, char *@var{end}) +This function clears the instruction cache between @var{beg} and @var{end}. +@end deftypefn + diff --git a/contrib/gcc/doc/makefile.texi b/contrib/gcc/doc/makefile.texi index 1e64c5e..4e91214 100644 --- a/contrib/gcc/doc/makefile.texi +++ b/contrib/gcc/doc/makefile.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 2001, 2002 Free Software Foundation, Inc. +@c Copyright (C) 2001, 2002, 2003, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -13,9 +13,17 @@ 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. Also, @samp{make dvi} is -available for DVI-formatted documentation, and @samp{make -generated-manpages} to generate man pages. +Produce info-formatted documentation and man pages. Essentially it +calls @samp{make man} and @samp{make info}. + +@item dvi +Produce DVI-formatted documentation. + +@item man +Generate man pages. + +@item info +Generate info-formatted pages. @item mostlyclean Delete the files made while building the compiler. @@ -26,14 +34,21 @@ That, and all the other files built by @samp{make all}. @item distclean That, and all the files created by @command{configure}. -@item extraclean -That, and any temporary or intermediate files, like emacs backup files. - @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 do not exist in CVS but +should go into a release tarball. One example is @file{gcc/c-parse.c} +which is generated from the CVS source file @file{gcc/c-parse.in}. + +@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. @@ -56,7 +71,7 @@ Note that running the testsuite may require additional tools be installed, such as TCL or dejagnu. @item bootstrap -Builds gcc three times---once with the native compiler, once with the +Builds GCC 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 step of this process @@ -68,21 +83,25 @@ Like @code{bootstrap}, except that the various stages are removed once they're no longer needed. This saves disk space. @item bubblestrap -Once bootstrapped, this incrementally rebuilds each of the three stages, -one at a time. It does this by ``bubbling'' the stages up from their -subdirectories, rebuilding them, and copying them back to their -subdirectories. This will allow you to, for example, quickly rebuild a -bootstrapped compiler after changing the sources, without having to do a -full bootstrap. +This incrementally rebuilds each of the three stages, one at a time. +It does this by ``bubbling'' the stages up from their subdirectories +(if they had been built previously), rebuilding them, and copying them +back to their subdirectories. This will allow you to, for example, +continue a bootstrap after fixing a bug which causes the stage2 build +to crash. @item quickstrap Rebuilds the most recently built stage. Since each stage requires -special invocation, using this target means you don't have to keep track -of which stage you're on or what invocation that stage needs. +special invocation, using this target means you don't have to keep +track of which stage you're on or what invocation that stage needs. @item cleanstrap Removed everything (@samp{make clean}) and rebuilds (@samp{make bootstrap}). +@item restrap +Like @code{cleanstrap}, except that the process starts from the first +stage build, not from scratch. + @item stage@var{N} (@var{N} = 1@dots{}4) For each stage, moves the appropriate files to the @file{stage@var{N}} subdirectory. @@ -99,4 +118,11 @@ 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 profiledbootstrap +Builds a compiler with profiling feedback information. For more +information, see +@ref{Building,,Building with profile feedback,gccinstall,Installing GCC}. +This is actually a target in the top-level directory, which then +recurses into the @file{gcc} subdirectory multiple times. + @end table diff --git a/contrib/gcc/doc/md.texi b/contrib/gcc/doc/md.texi index 822ec14..11e2915 100644 --- a/contrib/gcc/doc/md.texi +++ b/contrib/gcc/doc/md.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001, -@c 2002, 2003 Free Software Foundation, Inc. +@c 2002, 2003, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -181,7 +181,7 @@ this pattern. @xref{Insn Attributes}. Here is an actual example of an instruction pattern, for the 68000/68020. -@example +@smallexample (define_insn "tstsi" [(set (cc0) (match_operand:SI 0 "general_operand" "rm"))] @@ -192,12 +192,12 @@ Here is an actual example of an instruction pattern, for the 68000/68020. return \"tstl %0\"; return \"cmpl #0,%0\"; @}") -@end example +@end smallexample @noindent This can also be written using braced strings: -@example +@smallexample (define_insn "tstsi" [(set (cc0) (match_operand:SI 0 "general_operand" "rm"))] @@ -207,7 +207,7 @@ This can also be written using braced strings: return "tstl %0"; return "cmpl #0,%0"; @}) -@end example +@end smallexample This is an instruction that sets the condition codes based on the value of a general operand. It has no condition, so any insn whose RTL description @@ -1256,7 +1256,7 @@ instruction is defined: @dots{}) @end smallexample @end ifset -GCC can only handle one commutative pair in an asm; if you use more, +GCC can only handle one commutative pair in an asm; if you use more, the compiler may fail. @cindex @samp{#} in constraint @@ -1314,15 +1314,15 @@ The constraints are defined through these macros: @table @code @item REG_CLASS_FROM_LETTER -Register class constraints (usually lower case). +Register class constraints (usually lowercase). @item CONST_OK_FOR_LETTER_P Immediate constant constraints, for non-floating point constants of -word size or smaller precision (usually upper case). +word size or smaller precision (usually uppercase). @item CONST_DOUBLE_OK_FOR_LETTER_P Immediate constant constraints, for all floating point constants and for -constants of greater than word size precision (usually upper case). +constants of greater than word size precision (usually uppercase). @item EXTRA_CONSTRAINT Special cases of registers or memory. This macro is not required, and @@ -1439,7 +1439,7 @@ Constant integer 1 A floating point constant 0.0 @end table -@item IBM RS6000---@file{rs6000.h} +@item PowerPC and IBM RS6000---@file{rs6000.h} @table @code @item b Address base register @@ -1447,6 +1447,9 @@ Address base register @item f Floating point register +@item v +Vector register + @item h @samp{MQ}, @samp{CTR}, or @samp{LINK} register @@ -1825,11 +1828,11 @@ Non-pointer registers (not @samp{SP}, @samp{DP}, @samp{IP}) Non-SP registers (everything except @samp{SP}) @item R -Indirect thru @samp{IP} - Avoid this except for @code{QImode}, since we +Indirect through @samp{IP} - Avoid this except for @code{QImode}, since we can't access extra bytes @item S -Indirect thru @samp{SP} or @samp{DP} with short displacement (0..127) +Indirect through @samp{SP} or @samp{DP} with short displacement (0..127) @item T Data-section immediate value @@ -1934,12 +1937,6 @@ Data register @item f 68881 floating-point register, if available -@item x -Sun FPA (floating-point) register, if available - -@item y -First 16 Sun FPA registers, if available - @item I Integer in the range 1 to 8 @@ -1957,9 +1954,6 @@ Signed number whose magnitude is greater than 0x100 @item G Floating point constant that is not a 68881 constant - -@item H -Floating point constant that can be used by Sun FPA @end table @item Motorola 68HC11 & 68HC12 families---@file{m68hc11.h} @@ -2205,13 +2199,52 @@ Unsigned 12-bit constant (0--4095) Signed 16-bit constant (@minus{}32768--32767) @item L -Unsigned 16-bit constant (0--65535) +Value appropriate as displacement. +@table @code + @item (0..4095) + for short displacement + @item (-524288..524287) + for long displacement +@end table + +@item M +Constant integer with a value of 0x7fffffff. + +@item N +Multiple letter constraint followed by 4 parameter letters. +@table @code + @item 0..9: + number of the part counting from most to least significant + @item H,Q: + mode of the part + @item D,S,H: + mode of the containing operand + @item 0,F: + value of the other parts (F - all bits set) +@end table +The constraint matches if the specified part of a constant +has a value different from it's other parts. @item Q -Memory reference without index register +Memory reference without index register and with short displacement. + +@item R +Memory reference with index register and short displacement. @item S -Symbolic constant suitable for use with the @code{larl} instruction +Memory reference without index register but with long displacement. + +@item T +Memory reference with index register and long displacement. + +@item U +Pointer with short displacement. + +@item W +Pointer with long displacement. + +@item Y +Shift count operand. @end table @@ -2280,6 +2313,9 @@ The register indicated by Rx (not implemented yet). @item U A constant that is not between 2 and 15 inclusive. +@item Z +The constant 0. + @end table @item Xtensa---@file{xtensa.h} @@ -2324,7 +2360,7 @@ pattern to accomplish a certain task. @table @asis @cindex @code{mov@var{m}} instruction pattern @item @samp{mov@var{m}} -Here @var{m} stands for a two-letter machine mode name, in lower case. +Here @var{m} stands for a two-letter machine mode name, in lowercase. This instruction pattern moves data with that machine mode from operand 1 to operand 0. For example, @samp{movsi} moves full-word data. @@ -2627,6 +2663,72 @@ corresponds to the C data type @code{double} and the @code{logf} built-in function uses the mode which corresponds to the C data type @code{float}. +@cindex @code{pow@var{m}3} instruction pattern +@item @samp{pow@var{m}3} +Store the value of operand 1 raised to the exponent operand 2 +into operand 0. + +The @code{pow} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{powf} +built-in function uses the mode which corresponds to the C data +type @code{float}. + +@cindex @code{atan2@var{m}3} instruction pattern +@item @samp{atan2@var{m}3} +Store the arc tangent (inverse tangent) of operand 1 divided by +operand 2 into operand 0, using the signs of both arguments to +determine the quadrant of the result. + +The @code{atan2} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{atan2f} +built-in function uses the mode which corresponds to the C data +type @code{float}. + +@cindex @code{floor@var{m}2} instruction pattern +@item @samp{floor@var{m}2} +Store the largest integral value not greater than argument. + +The @code{floor} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{floorf} +built-in function uses the mode which corresponds to the C data +type @code{float}. + +@cindex @code{trunc@var{m}2} instruction pattern +@item @samp{trunc@var{m}2} +Store the argument rounded to integer towards zero. + +The @code{trunc} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{truncf} +built-in function uses the mode which corresponds to the C data +type @code{float}. + +@cindex @code{round@var{m}2} instruction pattern +@item @samp{round@var{m}2} +Store the argument rounded to integer away from zero. + +The @code{round} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{roundf} +built-in function uses the mode which corresponds to the C data +type @code{float}. + +@cindex @code{ceil@var{m}2} instruction pattern +@item @samp{ceil@var{m}2} +Store the argument rounded to integer away from zero. + +The @code{ceil} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{ceilf} +built-in function uses the mode which corresponds to the C data +type @code{float}. + +@cindex @code{nearbyint@var{m}2} instruction pattern +@item @samp{nearbyint@var{m}2} +Store the argument rounded according to the default rounding mode + +The @code{nearbyint} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{nearbyintf} +built-in function uses the mode which corresponds to the C data +type @code{float}. + @cindex @code{ffs@var{m}2} instruction pattern @item @samp{ffs@var{m}2} Store into operand 0 one plus the index of the least significant 1-bit @@ -2638,6 +2740,36 @@ generating the instruction. The @code{ffs} built-in function of C always uses the mode which corresponds to the C data type @code{int}. +@cindex @code{clz@var{m}2} instruction pattern +@item @samp{clz@var{m}2} +Store into operand 0 the number of leading 0-bits in @var{x}, starting +at the most significant bit position. If @var{x} is 0, the result is +undefined. @var{m} is the mode of operand 0; operand 1's mode is +specified by the instruction pattern, and the compiler will convert the +operand to that mode before generating the instruction. + +@cindex @code{ctz@var{m}2} instruction pattern +@item @samp{ctz@var{m}2} +Store into operand 0 the number of trailing 0-bits in @var{x}, starting +at the least significant bit position. If @var{x} is 0, the result is +undefined. @var{m} is the mode of operand 0; operand 1's mode is +specified by the instruction pattern, and the compiler will convert the +operand to that mode before generating the instruction. + +@cindex @code{popcount@var{m}2} instruction pattern +@item @samp{popcount@var{m}2} +Store into operand 0 the number of 1-bits in @var{x}. @var{m} is the +mode of operand 0; operand 1's mode is specified by the instruction +pattern, and the compiler will convert the operand to that mode before +generating the instruction. + +@cindex @code{parity@var{m}2} instruction pattern +@item @samp{parity@var{m}2} +Store into operand 0 the parity of @var{x}, i.@:e. the number of 1-bits +in @var{x} modulo 2. @var{m} is the mode of operand 0; operand 1's mode +is specified by the instruction pattern, and the compiler will convert +the operand to that mode before generating the instruction. + @cindex @code{one_cmpl@var{m}2} instruction pattern @item @samp{one_cmpl@var{m}2} Store the bitwise-complement of operand 1 into operand 0. @@ -2709,10 +2841,23 @@ The use for multiple @code{clrstr@var{m}} is as for @code{movstr@var{m}}. @cindex @code{cmpstr@var{m}} instruction pattern @item @samp{cmpstr@var{m}} -Block compare instruction, with five operands. Operand 0 is the output; +String compare instruction, with five operands. Operand 0 is the output; it has mode @var{m}. The remaining four operands are like the operands of @samp{movstr@var{m}}. The two memory blocks specified are compared -byte by byte in lexicographic order. The effect of the instruction is +byte by byte in lexicographic order starting at the beginning of each +string. The instruction is not allowed to prefetch more than one byte +at a time since either string may end in the first byte and reading past +that may access an invalid page or segment and cause a fault. The +effect of the instruction is to store a value in operand 0 whose sign +indicates the result of the comparison. + +@cindex @code{cmpmem@var{m}} instruction pattern +@item @samp{cmpmem@var{m}} +Block compare instruction, with five operands like the operands +of @samp{cmpstr@var{m}}. The two memory blocks specified are compared +byte by byte in lexicographic order starting at the beginning of each +block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch +any bytes in the two memory blocks. The effect of the instruction is to store a value in operand 0 whose sign indicates the result of the comparison. @@ -2829,6 +2974,13 @@ codes and vice versa. If the machine does not have conditional move instructions, do not define these patterns. +@cindex @code{add@var{mode}cc} instruction pattern +@item @samp{add@var{mode}cc} +Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally +move operand 2 or (operands 2 + operand 3) into operand 0 according to the +comparison in operand 1. If the comparison is true, operand 2 is moved into +operand 0, otherwise (operand 2 + operand 3) is moved. + @cindex @code{s@var{cond}} instruction pattern @item @samp{s@var{cond}} Store zero or nonzero in the operand according to the condition codes. @@ -3193,18 +3345,6 @@ Some machines require other operations such as stack probes or maintaining the back chain. Define this pattern to emit those operations in addition to updating the stack pointer. -@cindex @code{probe} instruction pattern -@item @samp{probe} -Some machines require instructions to be executed after space is -allocated from the stack, for example to generate a reference at -the bottom of the stack. - -If you need to emit instructions before the stack has been adjusted, -put them into the @samp{allocate_stack} pattern. Otherwise, define -this pattern to emit the required instructions. - -No operands are provided. - @cindex @code{check_stack} instruction pattern @item @samp{check_stack} If stack checking cannot be done on your system by probing the stack with @@ -3288,17 +3428,17 @@ and thence the call frame exception handling library routines, are built. It is intended to handle non-trivial actions needed along the abnormal return path. -The pattern takes two arguments. The first is an offset to be applied -to the stack pointer. It will have been copied to some appropriate -location (typically @code{EH_RETURN_STACKADJ_RTX}) which will survive -until after reload to when the normal epilogue is generated. -The second argument is the address of the exception handler to which -the function should return. This will normally need to copied by the -pattern to some special register or memory location. +The address of the exception handler to which the function should return +is passed as operand to this pattern. It will normally need to copied by +the pattern to some special register or memory location. +If the pattern needs to determine the location of the target call +frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX}, +if defined; it will have already been assigned. -This pattern only needs to be defined if call frame exception handling -is to be used, and simple moves involving @code{EH_RETURN_STACKADJ_RTX} -and @code{EH_RETURN_HANDLER_RTX} are not sufficient. +If this pattern is not defined, the default action will be to simply +copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either +that macro or this pattern needs to be defined if call frame exception +handling is to be used. @cindex @code{prologue} instruction pattern @anchor{prologue instruction pattern} @@ -3376,6 +3516,12 @@ the values of operands 1 and 2. @end table +@end ifset +@c Each of the following nodes are wrapped in separate +@c "@ifset INTERNALS" to work around memory limits for the default +@c configuration in older tetex distributions. Known to not work: +@c tetex-1.0.7, known to work: tetex-2.0.2. +@ifset INTERNALS @node Pattern Ordering @section When the Order of Patterns Matters @cindex Pattern Ordering @@ -3399,6 +3545,8 @@ Instead of using this pattern ordering it would be possible to make the pattern for convert-a-byte smart enough to deal properly with any constant value. +@end ifset +@ifset INTERNALS @node Dependent Patterns @section Interdependence of Patterns @cindex Dependent Patterns @@ -3408,24 +3556,24 @@ Every machine description must have a named pattern for each of the conditional branch names @samp{b@var{cond}}. The recognition template must always have the form -@example +@smallexample (set (pc) (if_then_else (@var{cond} (cc0) (const_int 0)) (label_ref (match_operand 0 "" "")) (pc))) -@end example +@end smallexample @noindent In addition, every machine description must have an anonymous pattern for each of the possible reverse-conditional branches. Their templates look like -@example +@smallexample (set (pc) (if_then_else (@var{cond} (cc0) (const_int 0)) (pc) (label_ref (match_operand 0 "" "")))) -@end example +@end smallexample @noindent They are necessary because jump optimization can turn direct-conditional @@ -3435,7 +3583,7 @@ It is often convenient to use the @code{match_operator} construct to reduce the number of patterns that must be specified for branches. For example, -@example +@smallexample (define_insn "" [(set (pc) (if_then_else (match_operator 0 "comparison_operator" @@ -3444,20 +3592,20 @@ example, (label_ref (match_operand 1 "" ""))))] "@var{condition}" "@dots{}") -@end example +@end smallexample In some cases machines support instructions identical except for the machine mode of one or more operands. For example, there may be ``sign-extend halfword'' and ``sign-extend byte'' instructions whose patterns are -@example +@smallexample (set (match_operand:SI 0 @dots{}) (extend:SI (match_operand:HI 1 @dots{}))) (set (match_operand:SI 0 @dots{}) (extend:SI (match_operand:QI 1 @dots{}))) -@end example +@end smallexample @noindent Constant integers do not specify a machine mode, so an instruction to @@ -3479,6 +3627,8 @@ instructions. Instead, they should be generated from the same pattern that supports register-register add insns by examining the operands and generating the appropriate machine instruction. +@end ifset +@ifset INTERNALS @node Jump Patterns @section Defining Jump Instruction Patterns @cindex jump instruction patterns @@ -3592,6 +3742,8 @@ discussed above, we have the pattern The @code{SELECT_CC_MODE} macro on the SPARC returns @code{CC_NOOVmode} for comparisons whose argument is a @code{plus}. +@end ifset +@ifset INTERNALS @node Looping Patterns @section Defining Looping Instruction Patterns @cindex looping instruction patterns @@ -3697,6 +3849,8 @@ be derived from it), however, in many cases the loop induction variable may become redundant and removed by the flow pass. +@end ifset +@ifset INTERNALS @node Insn Canonicalizations @section Canonicalization of Instructions @cindex canonicalization of instructions @@ -3731,7 +3885,7 @@ first operand. @item In combinations of @code{neg}, @code{mult}, @code{plus}, and @code{minus}, the @code{neg} operations (if any) will be moved inside -the operations as far as possible. For instance, +the operations as far as possible. For instance, @code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but @code{(plus (mult (neg A) B) C)} is canonicalized as @code{(minus A (mult B C))}. @@ -3770,26 +3924,26 @@ A machine that has an instruction that performs a bitwise logical-and of one operand with the bitwise negation of the other should specify the pattern for that instruction as -@example +@smallexample (define_insn "" [(set (match_operand:@var{m} 0 @dots{}) (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) (match_operand:@var{m} 2 @dots{})))] "@dots{}" "@dots{}") -@end example +@end smallexample @noindent Similarly, a pattern for a ``NAND'' instruction should be written -@example +@smallexample (define_insn "" [(set (match_operand:@var{m} 0 @dots{}) (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) (not:@var{m} (match_operand:@var{m} 2 @dots{}))))] "@dots{}" "@dots{}") -@end example +@end smallexample In both cases, it is not necessary to include patterns for the many logically equivalent RTL expressions. @@ -3804,9 +3958,9 @@ and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}. The sum of three items, one of which is a constant, will only appear in the form -@example +@smallexample (plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant}) -@end example +@end smallexample @item On machines that do not use @code{cc0}, @@ -3822,6 +3976,8 @@ will be written using @code{zero_extract} rather than the equivalent @end itemize +@end ifset +@ifset INTERNALS @node Expander Definitions @section Defining RTL Sequences for Code Generation @cindex expander definitions @@ -4039,6 +4195,8 @@ at the end, emit an insn to copy the result of the operation into itself. Such an insn will generate no code, but it can avoid problems in the compiler. +@end ifset +@ifset INTERNALS @node Insn Splitting @section Defining How to Split Instructions @cindex insn splitting @@ -4272,6 +4430,8 @@ functionality as two separate @code{define_insn} and @code{define_split} patterns. It exists for compactness, and as a maintenance tool to prevent having to ensure the two patterns' templates match. +@end ifset +@ifset INTERNALS @node Including Patterns @section Including Patterns in Machine Descriptions. @cindex insn includes @@ -4346,6 +4506,8 @@ one @option{-I} option, the directories are scanned in left-to-right order; the standard default directory come after. +@end ifset +@ifset INTERNALS @node Peephole Definitions @section Machine-Specific Peephole Optimizers @cindex peephole optimizer definitions @@ -4376,6 +4538,8 @@ targets that do scheduling. * define_peephole2:: RTL to RTL Peephole Optimizers @end menu +@end ifset +@ifset INTERNALS @node define_peephole @subsection RTL to Text Peephole Optimizers @findex define_peephole @@ -4567,6 +4731,8 @@ then the way to mention this insn in a peephole is as follows: @dots{}) @end smallexample +@end ifset +@ifset INTERNALS @node define_peephole2 @subsection RTL to RTL Peephole Optimizers @findex define_peephole2 @@ -4652,6 +4818,8 @@ If we had not added the @code{(match_dup 4)} in the middle of the input sequence, it might have been the case that the register we chose at the beginning of the sequence is killed by the first or second @code{set}. +@end ifset +@ifset INTERNALS @node Insn Attributes @section Instruction Attributes @cindex insn attributes @@ -4675,6 +4843,8 @@ to track the condition codes. * Processor pipeline description:: Specifying information for insn scheduling. @end menu +@end ifset +@ifset INTERNALS @node Defining Attributes @subsection Defining Attributes and their Values @cindex defining attributes and their values @@ -4710,9 +4880,9 @@ specified for an attribute, the following are defined: A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}. @item -An enumeral class is defined for @samp{attr_@var{name}} with +An enumerated class is defined for @samp{attr_@var{name}} with elements of the form @samp{@var{upper-name}_@var{upper-value}} where -the attribute name and value are first converted to upper case. +the attribute name and value are first converted to uppercase. @item A function @samp{get_attr_@var{name}} is defined that is passed an insn and @@ -4739,6 +4909,8 @@ If the attribute takes numeric values, no @code{enum} type will be defined and the function to obtain the attribute's value will return @code{int}. +@end ifset +@ifset INTERNALS @node Expressions @subsection Attribute Expressions @cindex attribute expressions @@ -4948,6 +5120,8 @@ for numeric attributes, as @code{eq_attr} and @code{attr_flag} produce more efficient code for non-numeric attributes. @end table +@end ifset +@ifset INTERNALS @node Tagging Insns @subsection Assigning Attribute Values to Insns @cindex tagging insns @@ -5053,6 +5227,8 @@ string. Therefore, the value of the @code{length} attribute specified in a @code{define_asm_attributes} should be the maximum possible length of a single machine instruction. +@end ifset +@ifset INTERNALS @node Attr Example @subsection Example of Attribute Specifications @cindex attribute specifications example @@ -5108,6 +5284,8 @@ performed on quantities smaller than a machine word clobber the condition code since they will set the condition code to a value corresponding to the full-word result. +@end ifset +@ifset INTERNALS @node Insn Lengths @subsection Computing the Length of an Insn @cindex insn lengths, computing @@ -5149,12 +5327,6 @@ Lengths are measured in addressable storage units (bytes). The following macros can be used to refine the length computation: @table @code -@findex FIRST_INSN_ADDRESS -@item FIRST_INSN_ADDRESS -When the @code{length} insn attribute is used, this macro specifies the -value to be assigned to the address of the first insn in a function. If -not specified, 0 is used. - @findex ADJUST_INSN_LENGTH @item ADJUST_INSN_LENGTH (@var{insn}, @var{length}) If defined, modifies the length assigned to instruction @var{insn} as a @@ -5198,6 +5370,8 @@ as follows: (const_int 6)))]) @end smallexample +@end ifset +@ifset INTERNALS @node Constant Attributes @subsection Constant Attributes @cindex constant attributes @@ -5227,6 +5401,8 @@ the value of a constant attribute may use the @code{symbol_ref} form, but may not use either the @code{match_operand} form or @code{eq_attr} forms involving insn attributes. +@end ifset +@ifset INTERNALS @node Delay Slots @subsection Delay Slot Scheduling @cindex delay slots, defining @@ -5302,6 +5478,8 @@ branch is true, we might represent this as follows: @end smallexample @c the above is *still* too long. --mew 4feb93 +@end ifset +@ifset INTERNALS @node Processor pipeline description @subsection Specifying processor pipeline description @cindex processor pipeline description @@ -5348,13 +5526,13 @@ processors. The task of exploiting more processor parallelism is solved by an instruction scheduler. For a better solution to this problem, the instruction scheduler has to have an adequate description of the -processor parallelism (or @dfn{pipeline description}). Currently GCC +processor parallelism (or @dfn{pipeline description}). Currently GCC provides two alternative ways to describe processor parallelism, both described below. The first method is outlined in the next section; it was once the only method provided by GCC, and thus is used in a number of exiting ports. The second, and preferred method, specifies functional unit reservations for groups of instructions with the aid of @dfn{regular -expressions}. This is called the @dfn{automaton based description}. +expressions}. This is called the @dfn{automaton based description}. The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to figure out the possibility of the instruction issue by the processor @@ -5367,18 +5545,18 @@ generated from the old description. Furthermore, its speed is not dependent on processor complexity. The instruction issue is possible if there is a transition from one automaton state to another one. -You can use any model to describe processor pipeline characteristics -or even a mix of them. You could use the old description for some -processor submodels and the @acronym{DFA}-based one for the rest +You can use either model to describe processor pipeline +characteristics or even mix them. You could use the old description +for some processor submodels and the @acronym{DFA}-based one for other processor submodels. -In general, the usage of the automaton based description is more -preferable. Its model is more rich. It permits to describe more -accurately pipeline characteristics of processors which results in -improving code quality (although sometimes only on several percent -fractions). It will be also used as an infrastructure to implement -sophisticated and practical insn scheduling which will try many -instruction sequences to choose the best one. +In general, using the automaton based description is preferred. Its +model is richer and makes it possible to more accurately describe +pipeline characteristics of processors, which results in improved +code quality (although sometimes only marginally). It will also be +used as an infrastructure to implement sophisticated and practical +instruction scheduling which will try many instruction sequences to +choose the best one. @menu @@ -5387,6 +5565,8 @@ instruction sequences to choose the best one. * Comparison of the two descriptions:: Drawbacks of the old pipeline description @end menu +@end ifset +@ifset INTERNALS @node Old pipeline description @subsubsection Specifying Function Units @cindex old pipeline description @@ -5501,14 +5681,17 @@ single or double precision, but not both, the following could be specified: @strong{Note:} The scheduler attempts to avoid function unit conflicts and uses all the specifications in the @code{define_function_unit} -expression. It has recently come to our attention that these +expression. It has recently been discovered that these specifications may not allow modeling of some of the newer ``superscalar'' processors that have insns using multiple pipelined units. These insns will cause a potential conflict for the second unit used during their execution and there is no way of representing that -conflict. We welcome any examples of how function unit conflicts work -in such processors and suggestions for their representation. +conflict. Any examples of how function unit conflicts work +in such processors and suggestions for their representation would be +welcomed. +@end ifset +@ifset INTERNALS @node Automaton pipeline description @subsubsection Describing instruction pipeline characteristics @cindex automaton based pipeline description @@ -5523,7 +5706,7 @@ The following optional construction describes names of automata generated and used for the pipeline hazards recognition. Sometimes the generated finite state automaton used by the pipeline hazard recognizer is large. If we use more than one automaton and bind functional -units to the automata, the total size of the automata is usually +units to the automata, the total size of the automata is usually less than the size of the single automaton. If there is no one such construction, only one finite state automaton is generated. @@ -5554,16 +5737,23 @@ which the unit is bound. The automaton should be described in construction @code{define_automaton}. You should give @dfn{automaton-name}, if there is a defined automaton. +The assignment of units to automata are constrained by the uses of the +units in insn reservations. The most important constraint is: if a +unit reservation is present on a particular cycle of an alternative +for an insn reservation, then some unit from the same automaton must +be present on the same cycle for the other alternatives of the insn +reservation. The rest of the constraints are mentioned in the +description of the subsequent constructions. + @findex define_query_cpu_unit @cindex querying function unit reservations The following construction describes CPU functional units analogously -to @code{define_cpu_unit}. If we use automata without their -minimization, the reservation of such units can be queried for an -automaton state. The instruction scheduler never queries reservation -of functional units for given automaton state. So as a rule, you -don't need this construction. This construction could be used for -future code generation goals (e.g. to generate @acronym{VLIW} insn -templates). +to @code{define_cpu_unit}. The reservation of such units can be +queried for an automaton state. The instruction scheduler never +queries reservation of functional units for given automaton state. So +as a rule, you don't need this construction. This construction could +be used for future code generation goals (e.g. to generate +@acronym{VLIW} insn templates). @smallexample (define_query_cpu_unit @var{unit-names} [@var{automaton-name}]) @@ -5630,7 +5820,7 @@ expression according to the following syntax: allof = allof "+" repeat | repeat - + repeat = element "*" number | element @@ -5712,23 +5902,31 @@ of insn @samp{store} (not a stored value). @findex exclusion_set @findex presence_set +@findex final_presence_set @findex absence_set +@findex final_absence_set @cindex VLIW @cindex RISC -Usually the following three constructions are used to describe -@acronym{VLIW} processors (more correctly to describe a placement of -small insns into @acronym{VLIW} insn slots). Although they can be -used for @acronym{RISC} processors too. +The following five constructions are usually used to describe +@acronym{VLIW} processors, or more precisely, to describe a placement +of small instructions into @acronym{VLIW} instruction slots. They +can be used for @acronym{RISC} processors, too. @smallexample (exclusion_set @var{unit-names} @var{unit-names}) -(presence_set @var{unit-names} @var{unit-names}) -(absence_set @var{unit-names} @var{unit-names}) +(presence_set @var{unit-names} @var{patterns}) +(final_presence_set @var{unit-names} @var{patterns}) +(absence_set @var{unit-names} @var{patterns}) +(final_absence_set @var{unit-names} @var{patterns}) @end smallexample @var{unit-names} is a string giving names of functional units separated by commas. +@var{patterns} is a string giving patterns of functional units +separated by comma. Currently pattern is is one unit or units +separated by white-spaces. + The first construction (@samp{exclusion_set}) means that each functional unit in the first string can not be reserved simultaneously with a unit whose name is in the second string and vice versa. For @@ -5739,22 +5937,75 @@ point insns or only double floating point insns. The second construction (@samp{presence_set}) means that each functional unit in the first string can not be reserved unless at -least one of units whose names are in the second string is reserved. -This is an asymmetric relation. For example, it is useful for -description that @acronym{VLIW} @samp{slot1} is reserved after -@samp{slot0} reservation. - -The third construction (@samp{absence_set}) means that each functional -unit in the first string can be reserved only if each unit whose name -is in the second string is not reserved. This is an asymmetric -relation (actually @samp{exclusion_set} is analogous to this one but -it is symmetric). For example, it is useful for description that -@acronym{VLIW} @samp{slot0} can not be reserved after @samp{slot1} or -@samp{slot2} reservation. +least one of pattern of units whose names are in the second string is +reserved. This is an asymmetric relation. For example, it is useful +for description that @acronym{VLIW} @samp{slot1} is reserved after +@samp{slot0} reservation. We could describe it by the following +construction + +@smallexample +(presence_set "slot1" "slot0") +@end smallexample + +Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0} +reservation. In this case we could write + +@smallexample +(presence_set "slot1" "slot0 b0") +@end smallexample + +The third construction (@samp{final_presence_set}) is analogous to +@samp{presence_set}. The difference between them is when checking is +done. When an instruction is issued in given automaton state +reflecting all current and planned unit reservations, the automaton +state is changed. The first state is a source state, the second one +is a result state. Checking for @samp{presence_set} is done on the +source state reservation, checking for @samp{final_presence_set} is +done on the result reservation. This construction is useful to +describe a reservation which is actually two subsequent reservations. +For example, if we use + +@smallexample +(presence_set "slot1" "slot0") +@end smallexample + +the following insn will be never issued (because @samp{slot1} requires +@samp{slot0} which is absent in the source state). + +@smallexample +(define_reservation "insn_and_nop" "slot0 + slot1") +@end smallexample + +but it can be issued if we use analogous @samp{final_presence_set}. + +The forth construction (@samp{absence_set}) means that each functional +unit in the first string can be reserved only if each pattern of units +whose names are in the second string is not reserved. This is an +asymmetric relation (actually @samp{exclusion_set} is analogous to +this one but it is symmetric). For example, it is useful for +description that @acronym{VLIW} @samp{slot0} can not be reserved after +@samp{slot1} or @samp{slot2} reservation. We could describe it by the +following construction + +@smallexample +(absence_set "slot2" "slot0, slot1") +@end smallexample + +Or @samp{slot2} can not be reserved if @samp{slot0} and unit @samp{b0} +are reserved or @samp{slot1} and unit @samp{b1} are reserved. In +this case we could write + +@smallexample +(absence_set "slot2" "slot0 b0, slot1 b1") +@end smallexample All functional units mentioned in a set should belong to the same automaton. +The last construction (@samp{final_absence_set}) is analogous to +@samp{absence_set} but checking is done on the result (state) +reservation. See comments for @samp{final_presence_set}. + @findex automata_option @cindex deterministic finite state automaton @cindex nondeterministic finite state automaton @@ -5797,6 +6048,14 @@ nondeterministic treatment means trying all alternatives, some of them may be rejected by reservations in the subsequent insns. You can not query functional unit reservations in nondeterministic automaton states. + +@item +@dfn{progress} means output of a progress bar showing how many states +were generated so far for automaton being processed. This is useful +during debugging a @acronym{DFA} description. If you see too many +generated states, you could interrupt the generator of the pipeline +hazard recognizer and try to figure out a reason for generation of the +huge automaton. @end itemize As an example, consider a superscalar @acronym{RISC} machine which can @@ -5855,6 +6114,8 @@ construction @end smallexample +@end ifset +@ifset INTERNALS @node Comparison of the two descriptions @subsubsection Drawbacks of the old pipeline description @cindex old pipeline description @@ -5868,7 +6129,7 @@ construction The old instruction level parallelism description and the pipeline hazards recognizer based on it have the following drawbacks in comparison with the @acronym{DFA}-based ones: - + @itemize @bullet @item Each functional unit is believed to be reserved at the instruction @@ -5908,6 +6169,8 @@ In an automaton based pipeline hazard recognizer, speed is not dependent on processor complexity. @end itemize +@end ifset +@ifset INTERNALS @node Conditional Execution @section Conditional Execution @cindex conditional execution @@ -5988,6 +6251,8 @@ generates a new pattern "(%3) add %2,%1,%0") @end smallexample +@end ifset +@ifset INTERNALS @node Constant Definitions @section Constant Definitions @cindex constant definitions diff --git a/contrib/gcc/doc/objc.texi b/contrib/gcc/doc/objc.texi index a0c40f7..481b51c 100644 --- a/contrib/gcc/doc/objc.texi +++ b/contrib/gcc/doc/objc.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001 Free Software Foundation, Inc. +@c 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -41,7 +41,7 @@ Suppose for example you have a @code{FileStream} class that declares @code{Stdin}, @code{Stdout} and @code{Stderr} as global variables, like below: -@example +@smallexample FileStream *Stdin = nil; FileStream *Stdout = nil; @@ -59,7 +59,7 @@ FileStream *Stderr = nil; /* Other methods here */ @@end -@end example +@end smallexample In this example, the initialization of @code{Stdin}, @code{Stdout} and @code{Stderr} in @code{+initialize} occurs too late. The programmer can @@ -73,7 +73,7 @@ just before entering @code{main}. The correct solution of the above problem is to use the @code{+load} method instead of @code{+initialize}: -@example +@smallexample @@implementation FileStream @@ -87,7 +87,7 @@ method instead of @code{+initialize}: /* Other methods here */ @@end -@end example +@end smallexample The @code{+load} is a method that is not overridden by categories. If a class and a category of it both implement @code{+load}, both methods are @@ -258,12 +258,12 @@ compiler on an i386 machine: @item Objective-C type @tab Compiler encoding @item -@example +@smallexample int a[10]; -@end example +@end smallexample @tab @code{[10i]} @item -@example +@smallexample struct @{ int i; float f[3]; @@ -271,7 +271,7 @@ struct @{ int b:2; char c; @} -@end example +@end smallexample @tab @code{@{?=i[3f]b128i3b131i2c@}} @end multitable @@ -343,7 +343,7 @@ Here is an example of how to use this feature. Suppose you want to implement a class whose instances hold a weak pointer reference; the following class does this: -@example +@smallexample @@interface WeakPointer : Object @{ @@ -375,7 +375,7 @@ following class does this: @@end -@end example +@end smallexample Weak pointers are supported through a new type character specifier represented by the @samp{!} character. The @@ -391,9 +391,9 @@ GNU Objective-C provides constant string objects that are generated directly by the compiler. You declare a constant string object by prefixing a C constant string with the character @samp{@@}: -@example +@smallexample id myString = @@"this is a constant string object"; -@end example +@end smallexample The constant string objects are by default instances of the @code{NXConstantString} class which is provided by the GNU Objective-C @@ -406,7 +406,7 @@ a new command line options @option{-fconstant-string-class=@var{class-name}}. The provided class should adhere to a strict structure, the same as @code{NXConstantString}'s structure: -@example +@smallexample @@interface MyConstantStringClass @{ @@ -416,7 +416,7 @@ as @code{NXConstantString}'s structure: @} @@end -@end example +@end smallexample @code{NXConstantString} inherits from @code{Object}; user class libraries may choose to inherit the customized constant string class @@ -455,9 +455,9 @@ forgotten, we are documenting it here. The keyword @code{@@compatibility_alias} allows you to define a class name as equivalent to another class name. For example: -@example +@smallexample @@compatibility_alias WOApplication GSWApplication; -@end example +@end smallexample tells the compiler that each time it encounters @code{WOApplication} as a class name, it should replace it with @code{GSWApplication} (that is, diff --git a/contrib/gcc/doc/passes.texi b/contrib/gcc/doc/passes.texi index 9a1941b..6bbc61c 100644 --- a/contrib/gcc/doc/passes.texi +++ b/contrib/gcc/doc/passes.texi @@ -1,5 +1,5 @@ -@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001 Free Software Foundation, Inc. +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +@c 2000, 2001, 2002, 2003 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -12,7 +12,10 @@ @cindex top level of compiler The overall control structure of the compiler is in @file{toplev.c}. This file is responsible for initialization, decoding arguments, opening and -closing files, and sequencing the passes. +closing files, and sequencing the passes. Routines for emitting +diagnostic messages are defined in @file{diagnostic.c}. The files +@file{pretty-print.h} and @file{pretty-print.c} provide basic support +for language-independent pretty-printing. @cindex parsing pass The parsing pass is invoked only once, to parse the entire input. A @@ -73,54 +76,27 @@ performed by cpplib, which is covered in separate documentation. In particular, the internals are covered in @xref{Top, ,Cpplib internals, cppinternals, Cpplib Internals}. -@c Avoiding overfull is tricky here. -The source files to parse C are -@file{c-convert.c}, -@file{c-decl.c}, -@file{c-errors.c}, -@file{c-lang.c}, -@file{c-objc-common.c}, -@file{c-parse.in}, -@file{c-aux-info.c}, -and -@file{c-typeck.c}, -along with a header file -@file{c-tree.h} -and some files shared with Objective-C and C++. - -The source files for parsing C++ are in @file{cp/}. -They are @file{parse.y}, -@file{class.c}, -@file{cvt.c}, @file{decl.c}, @file{decl2.c}, -@file{except.c}, -@file{expr.c}, @file{init.c}, @file{lex.c}, -@file{method.c}, @file{ptree.c}, -@file{search.c}, @file{spew.c}, -@file{semantics.c}, @file{tree.c}, -@file{typeck2.c}, and -@file{typeck.c}, along with header files @file{cp-tree.def}, -@file{cp-tree.h}, and @file{decl.h}. - -The special source files for parsing Objective-C are in @file{objc/}. -They are @file{objc-act.c}, @file{objc-tree.def}, and @file{objc-act.h}. -Certain C-specific files are used for this as well. - -The files -@file{c-common.c}, +The source files to parse C are found in the toplevel directory, and +by convention are named @file{c-*}. Some of these are also used by +the other C-like languages: @file{c-common.c}, @file{c-common.def}, @file{c-format.c}, @file{c-opts.c}, @file{c-pragma.c}, @file{c-semantics.c}, -and @file{c-lex.c}, -along with header files +@file{c-incpath.c}, +@file{c-ppoutput.c}, +@file{c-cppbuiltin.c}, @file{c-common.h}, @file{c-dump.h}, +@file{c.opt}, +@file{c-incpath.h} and @file{c-pragma.h}, -are also used for all of the above languages. +Files specific to each language are in subdirectories named after the +language in question, like @file{ada}, @file{objc}, @file{cp} (for C++). @cindex Tree optimization @item @@ -261,57 +237,6 @@ the second conditional test. The source code for this pass is in @file{jump.c}. This optimization is only performed if @option{-fthread-jumps} is enabled. -@cindex SSA optimizations -@cindex Single Static Assignment optimizations -@opindex fssa -@item -Static Single Assignment (SSA) based optimization passes. The -SSA conversion passes (to/from) are turned on by the @option{-fssa} -option (it is also done automatically if you enable an SSA optimization pass). -These passes utilize a form called Static Single Assignment. In SSA form, -each variable (pseudo register) is only set once, giving you def-use -and use-def chains for free, and enabling a lot more optimization -passes to be run in linear time. -Conversion to and from SSA form is handled by functions in -@file{ssa.c}. - -@opindex de -The option @option{-de} causes a debugging dump of the RTL code after -this pass. This dump file's name is made by appending @samp{.ssa} to -the input file name. -@itemize @bullet -@cindex SSA Conditional Constant Propagation -@cindex Conditional Constant Propagation, SSA based -@cindex conditional constant propagation -@opindex fssa-ccp -@item -SSA Conditional Constant Propagation. Turned on by the @option{-fssa-ccp} -option. This pass performs conditional constant propagation to simplify -instructions including conditional branches. This pass is more aggressive -than the constant propagation done by the CSE and GCSE passes, but operates -in linear time. - -@opindex dW -The option @option{-dW} causes a debugging dump of the RTL code after -this pass. This dump file's name is made by appending @samp{.ssaccp} to -the input file name. - -@cindex SSA DCE -@cindex DCE, SSA based -@cindex dead code elimination -@opindex fssa-dce -@item -SSA Aggressive Dead Code Elimination. Turned on by the @option{-fssa-dce} -option. This pass performs elimination of code considered unnecessary because -it has no externally visible effects on the program. It operates in -linear time. - -@opindex dX -The option @option{-dX} causes a debugging dump of the RTL code after -this pass. This dump file's name is made by appending @samp{.ssadce} to -the input file name. -@end itemize - @cindex common subexpression elimination @cindex constant propagation @item @@ -365,9 +290,41 @@ Its source files are @file{loop.c} and @file{unroll.c}, plus the header some functions in @file{integrate.c} and the header @file{integrate.h}. Loop dependency analysis routines are contained in @file{dependence.c}. +Second loop optimization pass takes care of basic block level optimizations -- +unrolling, peeling and unswitching loops. The source files are +@file{cfgloopanal.c} and @file{cfgloopmanip.c} containing generic loop +analysis and manipulation code, @file{loop-init.c} with initialization and +finalization code, @file{loop-unswitch.c} for loop unswitching and +@file{loop-unroll.c} for loop unrolling and peeling. + @opindex dL The option @option{-dL} causes a debugging dump of the RTL code after -this pass. This dump file's name is made by appending @samp{.loop} to +these passes. The dump file names are made by appending @samp{.loop} and +@samp{.loop2} to the input file name. + +@cindex jump bypassing +@item +Jump bypassing. This pass is an aggressive form of GCSE that transforms +the control flow graph of a function by propagating constants into +conditional branch instructions. + +The source file for this pass is @file{gcse.c}. + +@opindex dG +The option @option{-dG} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.bypass} +to the input file name. + +@cindex web construction +@item +Simple optimization pass that splits independent uses of each pseudo +increasing effect of other optimizations. This can improve effect of the +other transformation, such as CSE or register allocation. +Its source files are @file{web.c}. + +@opindex dZ +The option @option{-dZ} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.web} to the input file name. @item diff --git a/contrib/gcc/doc/portability.texi b/contrib/gcc/doc/portability.texi index b05698d..e65e979 100644 --- a/contrib/gcc/doc/portability.texi +++ b/contrib/gcc/doc/portability.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001, 2002 Free Software Foundation, Inc. +@c 1999, 2000, 2001, 2002, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -18,9 +18,9 @@ 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, I have not hesitated to define an ad-hoc parameter to the machine -description. The purpose of portability is to reduce the total work needed -on the compiler; it was not of interest for its own sake. +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 @@ -31,9 +31,10 @@ 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 I have not tried to address all possible -cases, but only the common ones or only the ones that I have encountered. -As a result, a new target may require additional strategies. You will know +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. diff --git a/contrib/gcc/doc/rtl.texi b/contrib/gcc/doc/rtl.texi index 605aad0..6fcce63 100644 --- a/contrib/gcc/doc/rtl.texi +++ b/contrib/gcc/doc/rtl.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002, 2003 +@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 @c Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -23,6 +23,7 @@ form uses nested parentheses to indicate the pointers in the internal form. * RTL Objects:: Expressions vs vectors vs strings vs integers. * RTL Classes:: Categories of RTL expression objects, and their structure. * Accessors:: Macros to access expression operands or vector elts. +* Special Accessors:: Macros to access specific annotations on RTL. * Flags:: Other flags in an RTL expression. * Machine Modes:: Describing the size and format of a datum. * Constants:: Expressions with constant values. @@ -98,7 +99,7 @@ null pointers are used instead. @findex PUT_CODE Expressions are classified by @dfn{expression codes} (also called RTX codes). The expression code is a name defined in @file{rtl.def}, which is -also (in upper case) a C enumeration constant. The possible expression +also (in uppercase) a C enumeration constant. The possible expression codes and their meanings are machine-independent. The code of an RTX can be extracted with the macro @code{GET_CODE (@var{x})} and altered with @code{PUT_CODE (@var{x}, @var{newcode})}. @@ -117,8 +118,8 @@ Expressions are written as parentheses containing the name of the expression type, its flags and machine mode if any, and then the operands of the expression (separated by spaces). -Expression code names in the @samp{md} file are written in lower case, -but when they appear in C code they are written in upper case. In this +Expression code names in the @samp{md} file are written in lowercase, +but when they appear in C code they are written in uppercase. In this manual, they are shown as follows: @code{const_int}. @cindex (nil) @@ -307,16 +308,16 @@ Operands of expressions are accessed using the macros @code{XEXP}, two arguments: an expression-pointer (RTX) and an operand number (counting from zero). Thus, -@example +@smallexample XEXP (@var{x}, 2) -@end example +@end smallexample @noindent accesses operand 2 of expression @var{x}, as an expression. -@example +@smallexample XINT (@var{x}, 2) -@end example +@end smallexample @noindent accesses the same operand as an integer. @code{XSTR}, used in the same @@ -368,6 +369,125 @@ All the macros defined in this section expand into lvalues and therefore can be used to assign the operands, lengths and vector elements as well as to access them. +@node Special Accessors +@section Access to Special Operands +@cindex access to special operands + +Some RTL nodes have special annotations associated with them. + +@table @code +@item MEM +@table @code +@findex MEM_ALIAS_SET +@item MEM_ALIAS_SET (@var{x}) +If 0, @var{x} is not in any alias set, and may alias anything. Otherwise, +@var{x} can only alias @code{MEM}s in a conflicting alias set. This value +is set in a language-dependent manner in the front-end, and should not be +altered in the back-end. In some front-ends, these numbers may correspond +in some way to types, or other language-level entities, but they need not, +and the back-end makes no such assumptions. +These set numbers are tested with @code{alias_sets_conflict_p}. + +@findex MEM_EXPR +@item MEM_EXPR (@var{x}) +If this register is known to hold the value of some user-level +declaration, this is that tree node. It may also be a +@code{COMPONENT_REF}, in which case this is some field reference, +and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration, +or another @code{COMPONENT_REF}, or null if there is no compile-time +object associated with the reference. + +@findex MEM_OFFSET +@item MEM_OFFSET (@var{x}) +The offset from the start of @code{MEM_EXPR} as a @code{CONST_INT} rtx. + +@findex MEM_SIZE +@item MEM_SIZE (@var{x}) +The size in bytes of the memory reference as a @code{CONST_INT} rtx. +This is mostly relevant for @code{BLKmode} references as otherwise +the size is implied by the mode. + +@findex MEM_ALIGN +@item MEM_ALIGN (@var{x}) +The known alignment in bits of the memory reference. +@end table + +@item REG +@table @code +@findex ORIGINAL_REGNO +@item ORIGINAL_REGNO (@var{x}) +This field holds the number the register ``originally'' had; for a +pseudo register turned into a hard reg this will hold the old pseudo +register number. + +@findex REG_EXPR +@item REG_EXPR (@var{x}) +If this register is known to hold the value of some user-level +declaration, this is that tree node. + +@findex REG_OFFSET +@item REG_OFFSET (@var{x}) +If this register is known to hold the value of some user-level +declaration, this is the offset into that logical storage. +@end table + +@item SYMBOL_REF +@table @code +@findex SYMBOL_REF_DECL +@item SYMBOL_REF_DECL (@var{x}) +If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or +a @code{FUNCTION_DECL}, that tree is recorded here. If this value is +null, then @var{x} was created by back end code generation routines, +and there is no associated front end symbol table entry. + +@code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'}, +that is, some sort of constant. In this case, the @code{symbol_ref} +is an entry in the per-file constant pool; again, there is no associated +front end symbol table entry. + +@findex SYMBOL_REF_FLAGS +@item SYMBOL_REF_FLAGS (@var{x}) +In a @code{symbol_ref}, this is used to communicate various predicates +about the symbol. Some of these are common enough to be computed by +common code, some are specific to the target. The common bits are: + +@table @code +@findex SYMBOL_REF_FUNCTION_P +@findex SYMBOL_FLAG_FUNCTION +@item SYMBOL_FLAG_FUNCTION +Set if the symbol refers to a function. + +@findex SYMBOL_REF_LOCAL_P +@findex SYMBOL_FLAG_LOCAL +@item SYMBOL_FLAG_LOCAL +Set if the symbol is local to this ``module''. +See @code{TARGET_BINDS_LOCAL_P}. + +@findex SYMBOL_REF_EXTERNAL_P +@findex SYMBOL_FLAG_EXTERNAL +@item SYMBOL_FLAG_EXTERNAL +Set if this symbol is not defined in this translation unit. +Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}. + +@findex SYMBOL_REF_SMALL_P +@findex SYMBOL_FLAG_SMALL +@item SYMBOL_FLAG_SMALL +Set if the symbol is located in the small data section. +See @code{TARGET_IN_SMALL_DATA_P}. + +@findex SYMBOL_FLAG_TLS_SHIFT +@findex SYMBOL_REF_TLS_MODEL +@item SYMBOL_REF_TLS_MODEL (@var{x}) +This is a multi-bit field accessor that returns the @code{tls_model} +to be used for a thread-local storage symbol. It returns zero for +non-thread-local symbols. +@end table + +Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for +the target's use. +@end table +@end table + @node Flags @section Flags in an RTL Expression @cindex flags in RTL expression @@ -515,6 +635,13 @@ In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions, nonzero for volatile memory references. Stored in the @code{volatil} field and printed as @samp{/v}. +@findex MEM_NOTRAP_P +@cindex @code{mem} and @samp{/c} +@cindex @code{call}, in @code{mem} +@item MEM_NOTRAP_P (@var{x}) +In @code{mem}, nonzero for memory references that will not trap. +Stored in the @code{call} field and printed as @samp{/c}. + @findex REG_FUNCTION_VALUE_P @cindex @code{reg} and @samp{/i} @cindex @code{integrated}, in @code{reg} @@ -732,7 +859,7 @@ These are the fields to which the above macros refer: @findex call @cindex @samp{/c} in RTL dump @item call -This flag is currently unused. +In a @code{mem}, 1 means that the memory reference will not trap. In an RTL dump, this flag is represented as @samp{/c}. @@ -1723,9 +1850,9 @@ Represents the signed product of the values represented by @var{x} and Some machines support a multiplication that generates a product wider than the operands. Write the pattern for this as -@example +@smallexample (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y})) -@end example +@end smallexample where @var{m} is wider than the modes of @var{x} and @var{y}, which need not be the same. @@ -1747,9 +1874,9 @@ Some machines have division instructions in which the operands and quotient widths are not all the same; you should represent such instructions using @code{truncate} and @code{sign_extend} as in, -@example +@smallexample (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y}))) -@end example +@end smallexample @findex udiv @cindex unsigned division @@ -1862,6 +1989,35 @@ Represents one plus the index of the least significant 1-bit in zero if @var{x} is zero.) The mode of @var{x} need not be @var{m}; depending on the target machine, various mode combinations may be valid. + +@findex clz +@item (clz:@var{m} @var{x}) +Represents the number of leading 0-bits in @var{x}, represented as an +integer of mode @var{m}, starting at the most significant bit position. +If @var{x} is zero, the value is determined by +@code{CLZ_DEFINED_VALUE_AT_ZERO}. Note that this is one of +the few expressions that is not invariant under widening. The mode of +@var{x} will usually be an integer mode. + +@findex ctz +@item (ctz:@var{m} @var{x}) +Represents the number of trailing 0-bits in @var{x}, represented as an +integer of mode @var{m}, starting at the least significant bit position. +If @var{x} is zero, the value is determined by +@code{CTZ_DEFINED_VALUE_AT_ZERO}. Except for this case, +@code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of +@var{x} will usually be an integer mode. + +@findex popcount +@item (popcount:@var{m} @var{x}) +Represents the number of 1-bits in @var{x}, represented as an integer of +mode @var{m}. The mode of @var{x} will usually be an integer mode. + +@findex parity +@item (parity:@var{m} @var{x}) +Represents the number of 1-bits modulo 2 in @var{x}, represented as an +integer of mode @var{m}. The mode of @var{x} will usually be an integer +mode. @end table @node Comparisons @@ -2054,11 +2210,6 @@ Describes a vector concat operation. The result is a concatenation of the vectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of the two inputs. -@findex vec_const -@item (vec_const:@var{m} @var{subparts}) -This describes a constant vector. @var{subparts} is a @code{parallel} that -contains a constant for each of the subparts of the vector. - @findex vec_duplicate @item (vec_duplicate:@var{m} @var{vec}) This operation converts a small vector into a larger one by duplicating the @@ -2081,9 +2232,9 @@ operation requires two operands of the same machine mode. Therefore, the byte-sized operand is enclosed in a conversion operation, as in -@example +@smallexample (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80)) -@end example +@end smallexample The conversion operation is not a mere placeholder, because there may be more than one way of converting from a given starting mode @@ -2227,7 +2378,7 @@ rest of the register receives an undefined value. Likewise, if the mode of the register, the rest of the register can be changed in an undefined way. -If @var{lval} is a @code{strict_low_part} or @code{zero_extract} +If @var{lval} is a @code{strict_low_part} or @code{zero_extract} of a @code{subreg}, then the part of the register specified by the machine mode of the @code{subreg} is given the value @var{x} and the rest of the register is not changed. @@ -2311,7 +2462,7 @@ trouble to describe the values that are stored, but it is essential to inform the compiler that the registers will be altered, lest it attempt to keep data in them across the string instruction. -If @var{x} is @code{(mem:BLK (const_int 0))} or +If @var{x} is @code{(mem:BLK (const_int 0))} or @code{(mem:BLK (scratch))}, it means that all memory locations must be presumed clobbered. If @var{x} is a @code{parallel}, it has the same meaning as a @code{parallel} in a @code{set} expression. @@ -2416,10 +2567,10 @@ side effect expressions---expressions of code @code{set}, @code{call}, side-effects are computed, and second all the actual side-effects are performed. For example, -@example +@smallexample (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1))) (set (mem:SI (reg:SI 1)) (reg:SI 1))]) -@end example +@end smallexample @noindent says unambiguously that the values of hard register 1 and the memory @@ -2432,13 +2583,13 @@ expect the result of one @code{set} to be available for the next one. For example, people sometimes attempt to represent a jump-if-zero instruction this way: -@example +@smallexample (parallel [(set (cc0) (reg:SI 34)) (set (pc) (if_then_else (eq (cc0) (const_int 0)) (label_ref @dots{}) (pc)))]) -@end example +@end smallexample @noindent But this is incorrect, because it says that the jump condition depends @@ -2565,9 +2716,9 @@ by is the length in bytes of the machine mode of the containing memory reference of which this expression serves as the address. Here is an example of its use: -@example +@smallexample (mem:DF (pre_dec:SI (reg:SI 39))) -@end example +@end smallexample @noindent This says to decrement pseudo register 39 by the length of a @code{DFmode} @@ -2727,16 +2878,16 @@ chain delimited by these insns, the @code{NEXT_INSN} and @code{PREV_INSN} pointers must always correspond: if @var{insn} is not the first insn, -@example +@smallexample NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn} -@end example +@end smallexample @noindent is always true and if @var{insn} is not the last insn, -@example +@smallexample PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn} -@end example +@end smallexample @noindent is always true. @@ -3198,13 +3349,6 @@ destination register. Thus, compiler passes prior to register allocation need only check for @code{REG_EQUAL} notes and passes subsequent to register allocation need only check for @code{REG_EQUIV} notes. - -@findex REG_WAS_0 -@item REG_WAS_0 -The single output of this insn contained zero before this insn. -@var{op} is the insn that set it to zero. You can rely on this note if -it is present and @var{op} has not been deleted or turned into a @code{note}; -its absence implies nothing. @end table These notes describe linkages between insns. They occur in pairs: one @@ -3315,9 +3459,9 @@ RTL expression code, @code{call}. @cindex @code{call} usage A @code{call} expression has two operands, as follows: -@example +@smallexample (call (mem:@var{fm} @var{addr}) @var{nbytes}) -@end example +@end smallexample @noindent Here @var{nbytes} is an operand that represents the number of bytes of @@ -3335,10 +3479,10 @@ For a subroutine that returns a value whose mode is not @code{BLKmode}, the value is returned in a hard register. If this register's number is @var{r}, then the body of the call insn looks like this: -@example +@smallexample (set (reg:@var{m} @var{r}) (call (mem:@var{fm} @var{addr}) @var{nbytes})) -@end example +@end smallexample @noindent This RTL expression makes it clear (to the optimizer passes) that the diff --git a/contrib/gcc/doc/sourcebuild.texi b/contrib/gcc/doc/sourcebuild.texi index c2222c0..af57f3a 100644 --- a/contrib/gcc/doc/sourcebuild.texi +++ b/contrib/gcc/doc/sourcebuild.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 2002, 2003 Free Software Foundation, Inc. +@c Copyright (C) 2002, 2003, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -14,7 +14,7 @@ which it is presumed that you are familiar. * Configure Terms:: Configuration terminology and history. * Top Level:: The top level source directory. * gcc Directory:: The @file{gcc} subdirectory. -* Test Suites:: The GCC test suites. +* Testsuites:: The GCC testsuites. @end menu @include configterms.texi @@ -44,7 +44,7 @@ front end. @item gcc The main sources of GCC itself (except for runtime libraries), including optimizers, support for different target architectures, -language front ends, and test suites. @xref{gcc Directory, , The +language front ends, and testsuites. @xref{gcc Directory, , The @file{gcc} Subdirectory}, for details. @item include @@ -91,7 +91,7 @@ configure, The GNU configure and build system}, for details. The @file{gcc} directory contains many files that are part of the C sources of GCC, other files used as part of the configuration and build process, and subdirectories including documentation and a -test suite. The files that are sources of GCC are documented in a +testsuite. The files that are sources of GCC are documented in a separate chapter. @xref{Passes, , Passes and Files of the Compiler}. @menu @@ -159,8 +159,8 @@ by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from which messages should not be extracted. @item testsuite -The GCC test suites (except for those for runtime libraries). -@xref{Test Suites}. +The GCC testsuites (except for those for runtime libraries). +@xref{Testsuites}. @end table @node Configuration @@ -168,14 +168,15 @@ The GCC test suites (except for those for runtime libraries). The @file{gcc} directory is configured with an Autoconf-generated script @file{configure}. The @file{configure} script is generated -from @file{configure.in} and @file{aclocal.m4}. From the files -@file{configure.in} and @file{acconfig.h}, Autoheader generates the +from @file{configure.ac} and @file{aclocal.m4}. From the files +@file{configure.ac} and @file{acconfig.h}, Autoheader generates the file @file{config.in}. The file @file{cstamp-h.in} is used as a timestamp. @menu * Config Fragments:: Scripts used by @file{configure}. -* System Config:: The @file{config.gcc} file. +* System Config:: The @file{config.build}, @file{config.host}, and + @file{config.gcc} files. * Configuration Files:: Files created by running @file{configure}. @end menu @@ -191,10 +192,14 @@ files, kept in the top level directory, are used. FIXME: when is the the top level one) used? @item The file @file{config.gcc} is used to handle configuration -specific to the particular build, host or target machine. (In -general, this should only be used for features that cannot reasonably -be tested in Autoconf feature tests.) @xref{System Config, , The -@file{config.gcc} File}, for details of the contents of this file. +specific to the particular target machine. The file +@file{config.build} is used to handle configuration specific to the +particular build machine. The file @file{config.host} is used to handle +configuration specific to the particular host machine. (In general, +these should only be used for features that cannot reasonably be tested in +Autoconf feature tests.) +@xref{System Config, , The @file{config.build}; @file{config.host}; +and @file{config.gcc} Files}, for details of the contents of these files. @item Each language subdirectory has a file @file{@var{language}/config-lang.in} that is used for @@ -206,9 +211,22 @@ creating the output of @file{configure}. @end itemize @node System Config -@subsubsection The @file{config.gcc} File +@subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files -FIXME: document the contents of this file, and what variables should +The @file{config.build} file contains specific rules for particular systems +which GCC is built on. This should be used as rarely as possible, as the +behavior of the build system can always be detected by autoconf. + +The @file{config.host} file contains specific rules for particular systems +which GCC will run on. This is rarely needed. + +The @file{config.gcc} file contains specific rules for particular systems +which GCC will generate code for. This is usually needed. + +Each file has a list of the shell variables it sets, with descriptions, at the +top of the file. + +FIXME: document the contents of these files, and what variables should be set to control build, host and target configuration. @include configfiles.texi @@ -258,7 +276,7 @@ headers to work with GCC, some other headers may also be installed in @file{config} to be installed on some systems. GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}. -This is done to cope with command-line options that change the +This is done to cope with command-line options that change the representation of floating point numbers. GCC also installs its own version of @code{<limits.h>}; this is generated @@ -432,6 +450,13 @@ files for that front end. @xref{Front End Directory, , The Front End A mention of the language in the list of supported languages in @file{gcc/doc/install.texi}. @item +A mention of the name under which the language's runtime library is +recognized by @option{--enable-shared=@var{package}} in the +documentation of that option in @file{gcc/doc/install.texi}. +@item +A mention of any special prerequisites for building the front end in +the documentation of prerequisites in @file{gcc/doc/install.texi}. +@item Details of contributors to that front end in @file{gcc/doc/contrib.texi}. If the details are in that front end's own manual then there should be a link to that manual's list in @@ -450,9 +475,9 @@ Details of source file suffixes for that language and @option{-x Entries in @code{default_compilers} in @file{gcc.c} for source file suffixes for that language. @item -Preferably test suites, which may be under @file{gcc/testsuite} or +Preferably testsuites, which may be under @file{gcc/testsuite} or runtime library directories. FIXME: document somewhere how to write -test suite harnesses. +testsuite harnesses. @item Probably a runtime library for the language, outside the @file{gcc} directory. FIXME: document this further. @@ -530,7 +555,12 @@ setting of @code{language} in @file{config-lang.in}) for the following values of @code{@var{hook}}, and any other Makefile rules required to build those targets (which may if necessary use other Makefiles specified in @code{outputs} in @file{config-lang.in}, although this is -deprecated). +deprecated). Some hooks are defined by using a double-colon rule for +@code{@var{hook}}, rather than by using a target of form +@code{@var{lang}.@var{hook}}. These hooks are called ``double-colon +hooks'' below. It also adds any testsuite targets that can use the +standard rule in @file{gcc/Makefile.in} to the variable +@code{lang_checks}. @table @code @item all.build @@ -538,8 +568,11 @@ deprecated). @itemx start.encap @itemx rest.encap FIXME: exactly what goes in each of these targets? +@item tags +Build an @command{etags} @file{TAGS} file in the language subdirectory +in the source tree. @item info -Build info documentation for the front end, in the source directory. +Build info documentation for the front end, in the build directory. This target is only called by @samp{make bootstrap} if a suitable version of @command{makeinfo} is available, so does not need to check for this, and should fail if an error occurs. @@ -547,9 +580,10 @@ for this, and should fail if an error occurs. Build DVI documentation for the front end, in the build directory. This should be done using @code{$(TEXI2DVI)}, with appropriate @option{-I} arguments pointing to directories of included files. -@item generated-manpages +This hook is a double-colon hook. +@item man Build generated man pages for the front end from Texinfo manuals -(@pxref{Man Page Generation}), in the source directory. This target +(@pxref{Man Page Generation}), in the build directory. This target is only called if the necessary tools are available, but should ignore errors so as not to stop the build if errors occur; man pages are optional and the tools involved may be installed in a broken way. @@ -558,17 +592,26 @@ FIXME: what is this target for? @item install-common Install everything that is part of the front end, apart from the compiler executables listed in @code{compilers} in -@file{config-lang.in} that are installed in @file{@var{libsubdir}} by -the main @file{Makefile}. +@file{config-lang.in}. @item install-info Install info documentation for the front end, if it is present in the -source directory. (It may not be present if a suitable version of -@command{makeinfo} was not installed.) This target should run the -command @command{install-info} to update the info directory, but -should ignore errors when running that command. +source directory. This target should have dependencies on info files +that should be installed. This hook is a double-colon hook. @item install-man Install man pages for the front end. This target should ignore errors. +@item srcextra +Copies its dependencies into the source directory. This generally should +be used for generated files such as @file{gcc/c-parse.c} which are not +present in CVS, but should be included in any release tarballs. This +target will be executed during a bootstrap if +@samp{--enable-generated-files-in-srcdir} was specified as a +@file{configure} option. +@item srcinfo +@itemx srcman +Copies its dependencies into the source directory. These targets will be +executed during a bootstrap if @samp{--enable-generated-files-in-srcdir} +was specified as a @file{configure} option. @item uninstall Uninstall files installed by installing the compiler. This is currently documented not to be supported, so the hook need not do @@ -576,28 +619,28 @@ anything. @item mostlyclean @itemx clean @itemx distclean -@itemx extraclean @itemx maintainer-clean -Except for @code{extraclean}, the language parts of the standard GNU +The language parts of the standard GNU @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for Users, standards, GNU Coding Standards}, for details of the standard -targets. @code{extraclean} does @code{distclean} and also deletes -anything likely to be found in the source directory that shouldn't be -in the distribution. For GCC, @code{maintainer-clean} should delete +targets. For GCC, @code{maintainer-clean} should delete all generated files in the source directory that are not checked into CVS, but should not delete anything checked into CVS@. @item stage1 @itemx stage2 @itemx stage3 @itemx stage4 +@itemx stageprofile +@itemx stagefeedback Move to the stage directory files not included in @code{stagestuff} in @file{config-lang.in} or otherwise moved by the main @file{Makefile}. @end table -@item lang-options.h -This file provides entries for @code{documented_lang_options} in -@file{toplev.c} describing command-line options the front end accepts -for @option{--help} output. +@item lang.opt +This file registers the set of switches that the front end accepts on +the command line, and their --help text. The file format is +documented in the file @file{c.opt}. These files are processed by the +script @file{opts.sh}. @item lang-specs.h This file provides entries for @code{default_compilers} in @file{gcc.c} which override the default of giving an error that a @@ -637,15 +680,15 @@ that should not be configured if this front end is not built. If defined to @samp{no}, this language front end is not built unless enabled in a @option{--enable-languages} argument. Otherwise, front ends are built by default, subject to any special logic in -@file{configure.in} (as is present to disable the Ada front end if the +@file{configure.ac} (as is present to disable the Ada front end if the Ada compiler is not already installed). @item boot_language If defined to @samp{yes}, this front end is built in stage 1 of the bootstrap. This is only relevant to front ends written in their own languages. @item compilers -If defined, a space-separated list of compiler executables that should -be installed in @file{@var{libsubdir}}. The names here will each end +If defined, a space-separated list of compiler executables that will +be run by the driver. The names here will each end with @samp{\$(exeext)}. @item stagestuff If defined, a space-separated list of files that should be moved to @@ -732,6 +775,9 @@ following are also necessary: An entry for the target architecture in @file{readings.html} on the GCC web site, with any relevant links. @item +Details of the properties of the back end and target architecture in +@file{backends.html} on the GCC web site. +@item A news item about the contribution of support for that target architecture, in @file{index.html} on the GCC web site. @item @@ -741,39 +787,48 @@ but it would be unusual to add support for a target that does not have a maintainer when support is added. @end itemize -@node Test Suites -@section Test Suites +@node Testsuites +@section Testsuites -GCC contains several test suites to help maintain compiler quality. -Most of the runtime libraries and language front ends in GCC have test -suites. Currently only the C language test suites are documented +GCC contains several testsuites to help maintain compiler quality. +Most of the runtime libraries and language front ends in GCC have +testsuites. Currently only the C language testsuites are documented here; FIXME: document the others. @menu -* Test Idioms:: Idioms used in test suite code. -* C Tests:: The C language test suites. -* libgcj Tests:: The Java library test suites. +* Test Idioms:: Idioms used in testsuite code. +* Ada Tests:: The Ada language testsuites. +* C Tests:: The C language testsuites. +* libgcj Tests:: The Java library testsuites. * gcov Testing:: Support for testing gcov. * profopt Testing:: Support for testing profile-directed optimizations. * compat Testing:: Support for testing binary compatibility. @end menu @node Test Idioms -@subsection Idioms Used in Test Suite Code - -In the @file{gcc.c-torture} test suites, test cases are commonly named -after the date on which they were added. This allows people to tell -at a glance whether a test failure is because of a recently found bug -that has not yet been fixed, or whether it may be a regression. In -other test suites, more descriptive names are used. In general C test -cases have a trailing @file{-@var{n}.c}, starting with @file{-1.c}, in -case other test cases with similar names are added later. +@subsection Idioms Used in Testsuite Code + +In general C testcases have a trailing @file{-@var{n}.c}, starting +with @file{-1.c}, in case other testcases with similar names are added +later. If the test is a test of some well-defined feature, it should +have a name referring to that feature such as +@file{@var{feature}-1.c}. If it does not test a well-defined feature +but just happens to exercise a bug somewhere in the compiler, and a +bug report has been filed for this bug in the GCC bug database, +@file{pr@var{bug-number}-1.c} is the appropriate form of name. +Otherwise (for miscellaneous bugs not filed in the GCC bug database), +and previously more generally, test cases are named after the date on +which they were added. This allows people to tell at a glance whether +a test failure is because of a recently found bug that has not yet +been fixed, or whether it may be a regression, but does not give any +other information about the bug or where discussion of it may be +found. Some other language testsuites follow similar conventions. Test cases should use @code{abort ()} to indicate failure and @code{exit (0)} for success; on some targets these may be redefined to indicate failure and success in other ways. -In the @file{gcc.dg} test suite, it is often necessary to test that an +In the @file{gcc.dg} testsuite, it is often necessary to test that an error is indeed a hard error and not just a warning---for example, where it is a constraint violation in the C standard, which must become an error with @option{-pedantic-errors}. The following idiom, @@ -831,26 +886,64 @@ All testcases must be portable. Target-specific testcases must have appropriate code to avoid causing failures on unsupported systems; unfortunately, the mechanisms for this differ by directory. -FIXME: discuss non-C test suites here. +FIXME: discuss non-C testsuites here. + +@node Ada Tests +@subsection Ada Language Testsuites + +The Ada testsuite includes executable tests from the ACATS 2.5 +testsuite, publicly available at +@uref{http://www.adaic.org/compilers/acats/2.5} + +These tests are integrated in the GCC testsuite in the +@file{gcc/testsuite/ada/acats} directory, and +enabled automatically when running @code{make check}, assuming +the Ada language has been enabled when configuring GCC. + +You can also run the Ada testsuite independently, using +@code{make check-ada}, or run a subset of the tests by specifying which +chapter to run, e.g: + +@smallexample +$ make check-ada CHAPTERS="c3 c9" +@end smallexample + +The tests are organized by directory, each directory corresponding to +a chapter of the Ada Reference Manual. So for example, c9 corresponds +to chapter 9, which deals with tasking features of the language. + +There is also an extra chapter called @file{gcc} containing a template for +creating new executable tests. + +The tests are run using two 'sh' scripts: run_acats and run_all.sh +To run the tests using a simulator or a cross target, see the small +customization section at the top of run_all.sh + +These tests are run using the build tree: they can be run without doing +a @code{make install}. @node C Tests -@subsection C Language Test Suites +@subsection C Language Testsuites -GCC contains the following C language test suites, in the +GCC contains the following C language testsuites, in the @file{gcc/testsuite} directory: @table @file @item gcc.dg -This contains tests of particular features of the C compiler, using the +This contains tests of particular features of the C compiler, using the more modern @samp{dg} harness. Correctness tests for various compiler features should go here if possible. -Magic comments determine whether the file -is preprocessed, compiled, linked or run. In these tests, error and warning -message texts are compared against expected texts or regular expressions +Magic comments determine whether the file +is preprocessed, compiled, linked or run. In these tests, error and warning +message texts are compared against expected texts or regular expressions given in comments. These tests are run with the options @samp{-ansi -pedantic} unless other options are given in the test. Except as noted below they are not run with multiple optimization options. +@item gcc.dg/compat +This subdirectory contains tests for binary compatibility using +@file{compat.exp}, which in turn uses the language-independent support +(@pxref{compat Testing, , Support for testing binary compatibility}). @item gcc.dg/cpp This subdirectory contains tests of the preprocessor. @item gcc.dg/debug @@ -872,7 +965,7 @@ FIXME: describe this. This contains particular code fragments which have historically broken easily. These tests are run with multiple optimization options, so tests for features which only break at some optimization levels belong here. This also contains -tests to check that certain optimizations occur. It might be worthwhile to +tests to check that certain optimizations occur. It might be worthwhile to separate the correctness tests cleanly from the code quality tests, but it hasn't been done yet. @@ -881,7 +974,7 @@ FIXME: describe this. This directory should probably not be used for new tests. @item gcc.c-torture/compile -This test suite contains test cases that should compile, but do not +This testsuite contains test cases that should compile, but do not need to link or run. These test cases are compiled with several different combinations of optimization options. All warnings are disabled for these test cases, so this directory is not suitable if @@ -891,7 +984,7 @@ platforms, by the use of @file{.x} files, mostly these test cases should not contain platform dependencies. FIXME: discuss how defines such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. @item gcc.c-torture/execute -This test suite contains test cases that should compile, link and run; +This testsuite contains test cases that should compile, link and run; otherwise the same comments as for @file{gcc.c-torture/compile} apply. @item gcc.c-torture/execute/ieee This contains tests which are specific to IEEE floating point. @@ -928,14 +1021,14 @@ FIXME: merge in @file{testsuite/README.gcc} and discuss the format of test cases and magic comments more. @node libgcj Tests -@subsection The Java library test suites. +@subsection The Java library testsuites. Runtime tests are executed via @samp{make check} in the @file{@var{target}/libjava/testsuite} directory in the build tree. Additional runtime tests can be checked into this testsuite. Regression testing of the core packages in libgcj is also covered by the -Mauve test suite. The @uref{http://sources.redhat.com/mauve/,,Mauve Project} +Mauve testsuite. The @uref{http://sources.redhat.com/mauve/,,Mauve Project} develops tests for the Java Class Libraries. These tests are run as part of libgcj testing by placing the Mauve tree within the libjava testsuite sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying @@ -949,8 +1042,8 @@ Update this file when adding new failing tests to Mauve, or when fixing bugs in libgcj that had caused Mauve test failures. The @uref{http://oss.software.ibm.com/developerworks/opensource/jacks/,, -Jacks} project provides a test suite for Java compilers that can be used -to test changes that affect the GCJ front end. This test suite is run as +Jacks} project provides a testsuite for Java compilers that can be used +to test changes that affect the GCJ front end. This testsuite is run as part of Java testing by placing the Jacks tree within the the libjava testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}. @@ -976,10 +1069,13 @@ and call return percentages. All of these checks are requested via commands that appear in comments in the test's source file. Commands to check line counts are processed by default. Commands to check branch percentages and call return percentages are -processed if there is a file with the same basename as the source -file and a suffix @file{.x} that contains a line -@code{set gcov_verify_branches 1} or @code{set gcov_verify_calls 1}, -respectively. +processed if the @command{run-gcov} command has arguments @code{branches} +or @code{calls}, respectively. For example, the following specifies +checking both, as well as passing @code{-b} to @command{gcov}: + +@smallexample +@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @} +@end smallexample A line count command appears within a comment on the source line that is expected to get the specified count and has the form @@ -1042,7 +1138,7 @@ about a specific optimization: @table @code @item tool -tool being tested, e.g., gcc +tool being tested, e.g., @command{gcc} @item profile_option options used to generate profile data @@ -1062,11 +1158,10 @@ torture tests @subsection Support for testing binary compatibility The file @file{compat.exp} provides language-independent support for -binary compatibility testing. It supports testing interoperability -of two compilers that follow the same ABI, or of multiple sets of -compiler options that should not affect binary compatibility. -It is intended to be used for test suites that complement ABI test -suites. +binary compatibility testing. It supports testing interoperability of +two compilers that follow the same ABI, or of multiple sets of +compiler options that should not affect binary compatibility. It is +intended to be used for testsuites that complement ABI testsuites. A test supported by this framework has three parts, each in a separate source file: a main program and two pieces that interact diff --git a/contrib/gcc/doc/standards.texi b/contrib/gcc/doc/standards.texi index c939498..af33612 100644 --- a/contrib/gcc/doc/standards.texi +++ b/contrib/gcc/doc/standards.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. +@c Copyright (C) 2000, 2001, 2002, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -79,7 +79,7 @@ as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or A new edition of the ISO C standard was published in 1999 as ISO/IEC 9899:1999, and is commonly known as @dfn{C99}. GCC has incomplete support for this standard version; see -@uref{http://gcc.gnu.org/gcc-3.3/c99status.html} for details. To select this +@uref{http://gcc.gnu.org/gcc-3.4/c99status.html} for details. To select this standard, use @option{-std=c99} or @option{-std=iso9899:1999}. (While in development, drafts of this standard version were referred to as @dfn{C9X}.) @@ -145,10 +145,10 @@ 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}. Some older ports of GCC are +@code{memset} and @code{memcmp}. Some older ports of GCC are configured to use the BSD @code{bcopy}, @code{bzero} and @code{bcmp} functions instead, but this is deprecated for new ports. -Finally, if @code{__builtin_trap} is used, and the target does +Finally, if @code{__builtin_trap} is used, and the target does not implement the @code{trap} pattern, then GCC will emit a call to @code{abort}. diff --git a/contrib/gcc/doc/tm.texi b/contrib/gcc/doc/tm.texi index 9a71173..03c1c4e 100644 --- a/contrib/gcc/doc/tm.texi +++ b/contrib/gcc/doc/tm.texi @@ -1,5 +1,5 @@ -@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002,2003 -@c Free Software Foundation, Inc. +@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001, +@c 2002, 2003, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -50,6 +50,7 @@ through the macros defined in the @file{.h} file. * Mode Switching:: Insertion of mode-switching instructions. * Target Attributes:: Defining target-specific uses of @code{__attribute__}. * MIPS Coprocessors:: MIPS coprocessor support and how to customize it. +* PCH Target:: Validity checking for precompiled headers. * Misc:: Everything else. @end menu @@ -93,9 +94,7 @@ from being defined in the @file{.h} file to being part of the @c prevent bad page break with this line You can control the compilation driver. -@table @code -@findex SWITCH_TAKES_ARG -@item SWITCH_TAKES_ARG (@var{char}) +@defmac SWITCH_TAKES_ARG (@var{char}) A C expression which determines whether the option @option{-@var{char}} takes arguments. The value should be the number of arguments that option takes--zero, for many options. @@ -106,9 +105,9 @@ properly. You need not define @code{SWITCH_TAKES_ARG} unless you wish to add additional options which take arguments. Any redefinition should call @code{DEFAULT_SWITCH_TAKES_ARG} and then check for additional options. +@end defmac -@findex WORD_SWITCH_TAKES_ARG -@item WORD_SWITCH_TAKES_ARG (@var{name}) +@defmac WORD_SWITCH_TAKES_ARG (@var{name}) A C expression which determines whether the option @option{-@var{name}} takes arguments. The value should be the number of arguments that option takes--zero, for many options. This macro rather than @@ -120,9 +119,9 @@ properly. You need not define @code{WORD_SWITCH_TAKES_ARG} unless you wish to add additional options which take arguments. Any redefinition should call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for additional options. +@end defmac -@findex SWITCH_CURTAILS_COMPILATION -@item SWITCH_CURTAILS_COMPILATION (@var{char}) +@defmac SWITCH_CURTAILS_COMPILATION (@var{char}) A C expression which determines whether the option @option{-@var{char}} stops compilation before the generation of an executable. The value is boolean, nonzero if the option does stop an executable from being @@ -135,16 +134,16 @@ options properly. You need not define options which affect the generation of an executable. Any redefinition should call @code{DEFAULT_SWITCH_CURTAILS_COMPILATION} and then check for additional options. +@end defmac -@findex SWITCHES_NEED_SPACES -@item SWITCHES_NEED_SPACES +@defmac SWITCHES_NEED_SPACES A string-valued C expression which enumerates the options for which the linker needs a space between the option and its argument. If this macro is not defined, the default value is @code{""}. +@end defmac -@findex TARGET_OPTION_TRANSLATE_TABLE -@item TARGET_OPTION_TRANSLATE_TABLE +@defmac TARGET_OPTION_TRANSLATE_TABLE If defined, a list of pairs of strings, the first of which is a potential command line target to the @file{gcc} driver program, and the second of which is a space-separated (tabs and other whitespace are not @@ -162,40 +161,60 @@ multilibs. Example nonsensical definition, where @code{-malt-abi}, @{ "-fast", "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \ @{ "-compat", "-EB -malign=4 -mspoo" @} @end smallexample +@end defmac -@findex DRIVER_SELF_SPECS -@item DRIVER_SELF_SPECS +@defmac DRIVER_SELF_SPECS A list of specs for the driver itself. It should be a suitable initializer for an array of strings, with no surrounding braces. -The driver applies these specs to its own command line before choosing -the multilib directory or running any subcommands. It applies them in -the order given, so each spec can depend on the options added by -earlier ones. It is also possible to remove options using -@samp{%<@var{option}} in the usual way. +The driver applies these specs to its own command line between loading +default @file{specs} files (but not command-line specified ones) and +choosing the multilib directory or running any subcommands. It +applies them in the order given, so each spec can depend on the +options added by earlier ones. It is also possible to remove options +using @samp{%<@var{option}} in the usual way. This macro can be useful when a port has several interdependent target options. It provides a way of standardizing the command line so that the other specs are easier to write. Do not define this macro if it does not need to do anything. +@end defmac + +@defmac OPTION_DEFAULT_SPECS +A list of specs used to support configure-time default options (i.e.@: +@option{--with} options) in the driver. It should be a suitable initializer +for an array of structures, each containing two strings, without the +outermost pair of surrounding braces. + +The first item in the pair is the name of the default. This must match +the code in @file{config.gcc} for the target. The second item is a spec +to apply if a default with this name was specified. The string +@samp{%(VALUE)} in the spec will be replaced by the value of the default +everywhere it occurs. + +The driver will apply these specs to its own command line between loading +default @file{specs} files and processing @code{DRIVER_SELF_SPECS}, using +the same mechanism as @code{DRIVER_SELF_SPECS}. + +Do not define this macro if it does not need to do anything. +@end defmac -@findex CPP_SPEC -@item CPP_SPEC +@defmac CPP_SPEC A C string constant that tells the GCC driver program options to pass to CPP@. It can also specify how to translate options you give to GCC into options for GCC to pass to the CPP@. Do not define this macro if it does not need to do anything. +@end defmac -@findex CPLUSPLUS_CPP_SPEC -@item CPLUSPLUS_CPP_SPEC +@defmac CPLUSPLUS_CPP_SPEC This macro is just like @code{CPP_SPEC}, but is used for C++, rather than C@. If you do not define this macro, then the value of @code{CPP_SPEC} (if any) will be used instead. +@end defmac -@findex CC1_SPEC -@item CC1_SPEC +@defmac CC1_SPEC A C string constant that tells the GCC driver program options to pass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language front ends. @@ -203,9 +222,9 @@ It can also specify how to translate options you give to GCC into options for GCC to pass to front ends. Do not define this macro if it does not need to do anything. +@end defmac -@findex CC1PLUS_SPEC -@item CC1PLUS_SPEC +@defmac CC1PLUS_SPEC A C string constant that tells the GCC driver program options to pass to @code{cc1plus}. It can also specify how to translate options you give to GCC into options for GCC to pass to the @code{cc1plus}. @@ -214,44 +233,57 @@ Do not define this macro if it does not need to do anything. Note that everything defined in CC1_SPEC is already passed to @code{cc1plus} so there is no need to duplicate the contents of CC1_SPEC in CC1PLUS_SPEC@. +@end defmac -@findex ASM_SPEC -@item ASM_SPEC +@defmac ASM_SPEC A C string constant that tells the GCC driver program options to pass to the assembler. It can also specify how to translate options you give to GCC into options for GCC to pass to the assembler. See the file @file{sun3.h} for an example of this. Do not define this macro if it does not need to do anything. +@end defmac -@findex ASM_FINAL_SPEC -@item ASM_FINAL_SPEC +@defmac ASM_FINAL_SPEC A C string constant that tells the GCC driver program how to run any programs which cleanup after the normal assembler. Normally, this is not needed. See the file @file{mips.h} for an example of this. Do not define this macro if it does not need to do anything. +@end defmac -@findex LINK_SPEC -@item LINK_SPEC +@defmac AS_NEEDS_DASH_FOR_PIPED_INPUT +Define this macro, with no value, if the driver should give the assembler +an argument consisting of a single dash, @option{-}, to instruct it to +read from its standard input (which will be a pipe connected to the +output of the compiler proper). This argument is given after any +@option{-o} option specifying the name of the output file. + +If you do not define this macro, the assembler is assumed to read its +standard input if given no non-option arguments. If your assembler +cannot read standard input at all, use a @samp{%@{pipe:%e@}} construct; +see @file{mips.h} for instance. +@end defmac + +@defmac LINK_SPEC A C string constant that tells the GCC driver program options to pass to the linker. It can also specify how to translate options you give to GCC into options for GCC to pass to the linker. Do not define this macro if it does not need to do anything. +@end defmac -@findex LIB_SPEC -@item LIB_SPEC +@defmac LIB_SPEC Another C string constant used much like @code{LINK_SPEC}. The difference between the two is that @code{LIB_SPEC} is used at the end of the command given to the linker. If this macro is not defined, a default is provided that loads the standard C library from the usual place. See @file{gcc.c}. +@end defmac -@findex LIBGCC_SPEC -@item LIBGCC_SPEC +@defmac LIBGCC_SPEC Another C string constant that tells the GCC driver program how and when to place a reference to @file{libgcc.a} into the linker command line. This constant is placed both before and after @@ -259,26 +291,26 @@ the value of @code{LIB_SPEC}. If this macro is not defined, the GCC driver provides a default that passes the string @option{-lgcc} to the linker. +@end defmac -@findex STARTFILE_SPEC -@item STARTFILE_SPEC +@defmac STARTFILE_SPEC Another C string constant used much like @code{LINK_SPEC}. The difference between the two is that @code{STARTFILE_SPEC} is used at the very beginning of the command given to the linker. If this macro is not defined, a default is provided that loads the standard C startup file from the usual place. See @file{gcc.c}. +@end defmac -@findex ENDFILE_SPEC -@item ENDFILE_SPEC +@defmac ENDFILE_SPEC Another C string constant used much like @code{LINK_SPEC}. The difference between the two is that @code{ENDFILE_SPEC} is used at the very end of the command given to the linker. Do not define this macro if it does not need to do anything. +@end defmac -@findex THREAD_MODEL_SPEC -@item THREAD_MODEL_SPEC +@defmac THREAD_MODEL_SPEC GCC @code{-v} will print the thread model GCC was configured to use. However, this doesn't work on platforms that are multilibbed on thread models, such as AIX 4.3. On such platforms, define @@ -286,9 +318,22 @@ models, such as AIX 4.3. On such platforms, define blanks that names one of the recognized thread models. @code{%*}, the default value of this macro, will expand to the value of @code{thread_file} set in @file{config.gcc}. +@end defmac + +@defmac SYSROOT_SUFFIX_SPEC +Define this macro to add a suffix to the target sysroot when GCC is +configured with a sysroot. This will cause GCC to search for usr/lib, +et al, within sysroot+suffix. +@end defmac -@findex EXTRA_SPECS -@item EXTRA_SPECS +@defmac SYSROOT_HEADERS_SUFFIX_SPEC +Define this macro to add a headers_suffix to the target sysroot when +GCC is configured with a sysroot. This will cause GCC to pass the +updated sysroot+headers_suffix to CPP, causing it to search for +usr/include, et al, within sysroot+headers_suffix. +@end defmac + +@defmac EXTRA_SPECS Define this macro to provide additional specifications to put in the @file{specs} file that can be used in various specifications like @code{CC1_SPEC}. @@ -311,20 +356,20 @@ used. The @file{config/rs6000/rs6000.h} target file defines: -@example +@smallexample #define EXTRA_SPECS \ @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @}, #define CPP_SYS_DEFAULT "" -@end example +@end smallexample The @file{config/rs6000/sysv.h} target file defines: @smallexample #undef CPP_SPEC #define CPP_SPEC \ "%@{posix: -D_POSIX_SOURCE @} \ -%@{mcall-sysv: -D_CALL_SYSV @} %@{mcall-aix: -D_CALL_AIX @} \ -%@{!mcall-sysv: %@{!mcall-aix: %(cpp_sysv_default) @}@} \ +%@{mcall-sysv: -D_CALL_SYSV @} \ +%@{!mcall-sysv: %(cpp_sysv_default) @} \ %@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}" #undef CPP_SYSV_DEFAULT @@ -338,30 +383,30 @@ while the @file{config/rs6000/eabiaix.h} target file defines #undef CPP_SYSV_DEFAULT #define CPP_SYSV_DEFAULT "-D_CALL_AIX" @end smallexample +@end defmac -@findex LINK_LIBGCC_SPECIAL -@item LINK_LIBGCC_SPECIAL +@defmac LINK_LIBGCC_SPECIAL Define this macro if the driver program should find the library @file{libgcc.a} itself and should not pass @option{-L} options to the linker. If you do not define this macro, the driver program will pass the argument @option{-lgcc} to tell the linker to do the search and will pass @option{-L} options to it. +@end defmac -@findex LINK_LIBGCC_SPECIAL_1 -@item LINK_LIBGCC_SPECIAL_1 +@defmac LINK_LIBGCC_SPECIAL_1 Define this macro if the driver program should find the library @file{libgcc.a}. If you do not define this macro, the driver program will pass the argument @option{-lgcc} to tell the linker to do the search. This macro is similar to @code{LINK_LIBGCC_SPECIAL}, except that it does not affect @option{-L} options. +@end defmac -@findex LINK_GCC_C_SEQUENCE_SPEC -@item LINK_GCC_C_SEQUENCE_SPEC +@defmac LINK_GCC_C_SEQUENCE_SPEC The sequence in which libgcc and libc are specified to the linker. By default this is @code{%G %L %G}. +@end defmac -@findex LINK_COMMAND_SPEC -@item LINK_COMMAND_SPEC +@defmac LINK_COMMAND_SPEC A C string constant giving the complete command line need to execute the linker. When you do this, you will need to update your port each time a change is made to the link command line within @file{gcc.c}. Therefore, @@ -369,15 +414,15 @@ define this macro only if you need to completely redefine the command line for invoking the linker and there is no other way to accomplish the effect you need. Overriding this macro may be avoidable by overriding @code{LINK_GCC_C_SEQUENCE_SPEC} instead. +@end defmac -@findex LINK_ELIMINATE_DUPLICATE_LDIRECTORIES -@item LINK_ELIMINATE_DUPLICATE_LDIRECTORIES +@defmac LINK_ELIMINATE_DUPLICATE_LDIRECTORIES A nonzero value causes @command{collect2} to remove duplicate @option{-L@var{directory}} search directories from linking commands. Do not give it a nonzero value if removing duplicate search directories changes the linker's semantics. +@end defmac -@findex MULTILIB_DEFAULTS -@item MULTILIB_DEFAULTS +@defmac MULTILIB_DEFAULTS Define this macro as a C expression for the initializer of an array of string to tell the driver program which options are defaults for this target and thus do not need to be handled specially when using @@ -387,55 +432,51 @@ Do not define this macro if @code{MULTILIB_OPTIONS} is not defined in the target makefile fragment or if none of the options listed in @code{MULTILIB_OPTIONS} are set by default. @xref{Target Fragment}. +@end defmac -@findex RELATIVE_PREFIX_NOT_LINKDIR -@item RELATIVE_PREFIX_NOT_LINKDIR +@defmac RELATIVE_PREFIX_NOT_LINKDIR Define this macro to tell @command{gcc} that it should only translate a @option{-B} prefix into a @option{-L} linker option if the prefix indicates an absolute file name. +@end defmac -@findex STANDARD_EXEC_PREFIX -@item STANDARD_EXEC_PREFIX -Define this macro as a C string constant if you wish to override the -standard choice of @file{/usr/local/lib/gcc-lib/} as the default prefix to -try when searching for the executable files of the compiler. - -@findex MD_EXEC_PREFIX -@item MD_EXEC_PREFIX +@defmac MD_EXEC_PREFIX If defined, this macro is an additional prefix to try after @code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched when the @option{-b} option is used, or the compiler is built as a cross compiler. If you define @code{MD_EXEC_PREFIX}, then be sure to add it to the list of directories used to find the assembler in @file{configure.in}. +@end defmac -@findex STANDARD_STARTFILE_PREFIX -@item STANDARD_STARTFILE_PREFIX +@defmac STANDARD_STARTFILE_PREFIX Define this macro as a C string constant if you wish to override the -standard choice of @file{/usr/local/lib/} as the default prefix to +standard choice of @code{libdir} as the default prefix to try when searching for startup files such as @file{crt0.o}. +@code{STANDARD_STARTFILE_PREFIX} is not searched when the compiler +is built as a cross compiler. +@end defmac -@findex MD_STARTFILE_PREFIX -@item MD_STARTFILE_PREFIX +@defmac MD_STARTFILE_PREFIX If defined, this macro supplies an additional prefix to try after the standard prefixes. @code{MD_EXEC_PREFIX} is not searched when the @option{-b} option is used, or when the compiler is built as a cross compiler. +@end defmac -@findex MD_STARTFILE_PREFIX_1 -@item MD_STARTFILE_PREFIX_1 +@defmac MD_STARTFILE_PREFIX_1 If defined, this macro supplies yet another prefix to try after the standard prefixes. It is not searched when the @option{-b} option is used, or when the compiler is built as a cross compiler. +@end defmac -@findex INIT_ENVIRONMENT -@item INIT_ENVIRONMENT +@defmac INIT_ENVIRONMENT Define this macro as a C string constant if you wish to set environment variables for programs called by the driver, such as the assembler and loader. The driver passes the value of this macro to @code{putenv} to initialize the necessary environment variables. +@end defmac -@findex LOCAL_INCLUDE_DIR -@item LOCAL_INCLUDE_DIR +@defmac LOCAL_INCLUDE_DIR Define this macro as a C string constant if you wish to override the standard choice of @file{/usr/local/include} as the default prefix to try when searching for local header files. @code{LOCAL_INCLUDE_DIR} @@ -443,11 +484,11 @@ comes before @code{SYSTEM_INCLUDE_DIR} in the search order. Cross compilers do not search either @file{/usr/local/include} or its replacement. +@end defmac -@findex MODIFY_TARGET_NAME -@item MODIFY_TARGET_NAME -Define this macro if you with to define command-line switches that modify the -default target name +@defmac MODIFY_TARGET_NAME +Define this macro if you wish to define command-line switches that +modify the default target name. For each switch, you can include a string to be appended to the first part of the configuration name or a string to be deleted from the @@ -468,10 +509,9 @@ code @{ @{ "-32", DELETE, "64"@}, \ @{"-64", ADD, "64"@}@} @end smallexample +@end defmac - -@findex SYSTEM_INCLUDE_DIR -@item SYSTEM_INCLUDE_DIR +@defmac SYSTEM_INCLUDE_DIR Define this macro as a C string constant if you wish to specify a system-specific directory to search for header files before the standard directory. @code{SYSTEM_INCLUDE_DIR} comes before @@ -479,24 +519,24 @@ directory. @code{SYSTEM_INCLUDE_DIR} comes before Cross compilers do not use this macro and do not search the directory specified. +@end defmac -@findex STANDARD_INCLUDE_DIR -@item STANDARD_INCLUDE_DIR +@defmac STANDARD_INCLUDE_DIR Define this macro as a C string constant if you wish to override the standard choice of @file{/usr/include} as the default prefix to try when searching for header files. -Cross compilers do not use this macro and do not search either +Cross compilers ignore this macro and do not search either @file{/usr/include} or its replacement. +@end defmac -@findex STANDARD_INCLUDE_COMPONENT -@item STANDARD_INCLUDE_COMPONENT +@defmac STANDARD_INCLUDE_COMPONENT The ``component'' corresponding to @code{STANDARD_INCLUDE_DIR}. See @code{INCLUDE_DEFAULTS}, below, for the description of components. If you do not define this macro, no component is used. +@end defmac -@findex INCLUDE_DEFAULTS -@item INCLUDE_DEFAULTS +@defmac INCLUDE_DEFAULTS Define this macro if you wish to override the entire default search path for include files. For a native compiler, the default search path usually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR}, @@ -515,13 +555,13 @@ wrapped in @code{extern @samp{C}} when compiling C++. Mark the end of the array with a null element. The component name denotes what GNU package the include file is part of, -if any, in all upper-case letters. For example, it might be @samp{GCC} +if any, in all uppercase letters. For example, it might be @samp{GCC} or @samp{BINUTILS}. If the package is part of a vendor-supplied operating system, code the component name as @samp{0}. For example, here is the definition used for VAX/VMS: -@example +@smallexample #define INCLUDE_DEFAULTS \ @{ \ @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \ @@ -530,8 +570,8 @@ For example, here is the definition used for VAX/VMS: @{ ".", 0, 0, 0@}, \ @{ 0, 0, 0, 0@} \ @} -@end example -@end table +@end smallexample +@end defmac Here is the order of prefixes tried for exec files: @@ -599,13 +639,11 @@ The macro @code{STANDARD_STARTFILE_PREFIX}. @c prevent bad page break with this line Here are run-time target specifications. -@table @code -@findex TARGET_CPU_CPP_BUILTINS -@item TARGET_CPU_CPP_BUILTINS() +@defmac TARGET_CPU_CPP_BUILTINS () This function-like macro expands to a block of code that defines built-in preprocessor macros and assertions for the target cpu, using the functions @code{builtin_define}, @code{builtin_define_std} and -@code{builtin_assert} defined in @file{c-common.c}. When the front end +@code{builtin_assert}. When the front end calls this macro it provides a trailing semicolon, and since it has finished command line option processing your code can use those results freely. @@ -635,48 +673,28 @@ to check for that first. If you need to check for strict ANSI, the variable @code{flag_iso} can be used. The function-like macro @code{preprocessing_trad_p()} can be used to check for traditional preprocessing. +@end defmac -With @code{TARGET_OS_CPP_BUILTINS} this macro obsoletes the -@code{CPP_PREDEFINES} target macro. - -@findex TARGET_OS_CPP_BUILTINS -@item TARGET_OS_CPP_BUILTINS() +@defmac TARGET_OS_CPP_BUILTINS () Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional and is used for the target operating system instead. +@end defmac -With @code{TARGET_CPU_CPP_BUILTINS} this macro obsoletes the -@code{CPP_PREDEFINES} target macro. - -@findex CPP_PREDEFINES -@item CPP_PREDEFINES -Define this to be a string constant containing @option{-D} options to -define the predefined macros that identify this machine and system. -These macros will be predefined unless the @option{-ansi} option (or a -@option{-std} option for strict ISO C conformance) is specified. - -In addition, a parallel set of macros are predefined, whose names are -made by appending @samp{__} at the beginning and at the end. These -@samp{__} macros are permitted by the ISO standard, so they are -predefined regardless of whether @option{-ansi} or a @option{-std} option -is specified. - -For example, on the Sun, one can use the following value: - -@smallexample -"-Dmc68000 -Dsun -Dunix" -@end smallexample - -The result is to define the macros @code{__mc68000__}, @code{__sun__} -and @code{__unix__} unconditionally, and the macros @code{mc68000}, -@code{sun} and @code{unix} provided @option{-ansi} is not specified. +@defmac TARGET_OBJFMT_CPP_BUILTINS () +Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional +and is used for the target object format. @file{elfos.h} uses this +macro to define @code{__ELF__}, so you probably do not need to define +it yourself. +@end defmac -@findex extern int target_flags -@item extern int target_flags; +@deftypevar {extern int} target_flags This declaration should be present. +@end deftypevar @cindex optional hardware or system features @cindex features, optional, in system conventions -@item TARGET_@dots{} + +@defmac TARGET_@var{featurename} This series of macros is to allow compiler command arguments to enable or disable the use of optional features of the target machine. For example, one machine description serves both the 68000 and @@ -687,14 +705,14 @@ by means of a macro @code{TARGET_68020} that tests a bit in Define a macro @code{TARGET_@var{featurename}} for each such option. Its definition should test a bit in @code{target_flags}. It is -recommended that a helper macro @code{TARGET_MASK_@var{featurename}} +recommended that a helper macro @code{MASK_@var{featurename}} is defined for each bit-value to test, and used in @code{TARGET_@var{featurename}} and @code{TARGET_SWITCHES}. For example: @smallexample #define TARGET_MASK_68020 1 -#define TARGET_68020 (target_flags & TARGET_MASK_68020) +#define TARGET_68020 (target_flags & MASK_68020) @end smallexample One place where these macros are used is in the condition-expressions @@ -702,9 +720,9 @@ of instruction patterns. Note how @code{TARGET_68020} appears frequently in the 68000 machine description file, @file{m68k.md}. Another place they are used is in the definitions of the other macros in the @file{@var{machine}.h} file. +@end defmac -@findex TARGET_SWITCHES -@item TARGET_SWITCHES +@defmac TARGET_SWITCHES This macro defines names of command options to set and clear bits in @code{target_flags}. Its definition is an initializer with a subgrouping for each command option. @@ -735,29 +753,39 @@ with opposite meanings, and picks the latter as the default: @smallexample #define TARGET_SWITCHES \ - @{ @{ "68020", TARGET_MASK_68020, "" @}, \ - @{ "68000", -TARGET_MASK_68020, \ + @{ @{ "68020", MASK_68020, "" @}, \ + @{ "68000", -MASK_68020, \ N_("Compile for the 68000") @}, \ - @{ "", TARGET_MASK_68020, "" @}@} + @{ "", MASK_68020, "" @}, \ + @} @end smallexample +@end defmac -@findex TARGET_OPTIONS -@item TARGET_OPTIONS +@defmac TARGET_OPTIONS This macro is similar to @code{TARGET_SWITCHES} but defines names of command options that have values. Its definition is an initializer with a subgrouping for each command option. -Each subgrouping contains a string constant, that defines the fixed part -of the option name, the address of a variable, and a description string. -Non-empty description strings should be marked with @code{N_(@dots{})} for -@command{xgettext}. Please do not mark empty strings because the empty -string is reserved by GNU gettext. @code{gettext("")} returns the header entry -of the message catalog with meta information, not the empty string. +Each subgrouping contains a string constant, that defines the option +name, the address of a variable, a description string, and a value. +Non-empty description strings should be marked with @code{N_(@dots{})} +for @command{xgettext}. Please do not mark empty strings because the +empty string is reserved by GNU gettext. @code{gettext("")} returns the +header entry of the message catalog with meta information, not the empty +string. + +If the value listed in the table is @code{NULL}, then the variable, type +@code{char *}, is set to the variable part of the given option if the +fixed part matches. In other words, if the first part of the option +matches what's in the table, the variable will be set to point to the +rest of the option. This allows the user to specify a value for that +option. The actual option name is made by appending @samp{-m} to the +specified name. Again, each option should also be documented in +@file{invoke.texi}. -The variable, type @code{char *}, is set to the variable part of the -given option if the fixed part matches. The actual option name is made -by appending @samp{-m} to the specified name. Again, each option should -also be documented in @file{invoke.texi}. +If the value listed in the table is non-@code{NULL}, then the option +must match the option in the table exactly (with @samp{-m}), and the +variable is set to point to the value listed in the table. Here is an example which defines @option{-mshort-data-@var{number}}. If the given option is @option{-mshort-data-512}, the variable @code{m88k_short_data} @@ -767,11 +795,42 @@ will be set to the string @code{"512"}. extern char *m88k_short_data; #define TARGET_OPTIONS \ @{ @{ "short-data-", &m88k_short_data, \ - N_("Specify the size of the short data section") @} @} + N_("Specify the size of the short data section"), 0 @} @} +@end smallexample + +Here is a variant of the above that allows the user to also specify +just @option{-mshort-data} where a default of @code{"64"} is used. + +@smallexample +extern char *m88k_short_data; +#define TARGET_OPTIONS \ + @{ @{ "short-data-", &m88k_short_data, \ + N_("Specify the size of the short data section"), 0 @} \ + @{ "short-data", &m88k_short_data, "", "64" @}, + @} +@end smallexample + +Here is an example which defines @option{-mno-alu}, @option{-malu1}, and +@option{-malu2} as a three-state switch, along with suitable macros for +checking the state of the option (documentation is elided for brevity). + +@smallexample +[chip.c] +char *chip_alu = ""; /* Specify default here. */ + +[chip.h] +extern char *chip_alu; +#define TARGET_OPTIONS \ + @{ @{ "no-alu", &chip_alu, "", "" @}, \ + @{ "alu1", &chip_alu, "", "1" @}, \ + @{ "alu2", &chip_alu, "", "2" @}, @} +#define TARGET_ALU (chip_alu[0] != '\0') +#define TARGET_ALU1 (chip_alu[0] == '1') +#define TARGET_ALU2 (chip_alu[0] == '2') @end smallexample +@end defmac -@findex TARGET_VERSION -@item TARGET_VERSION +@defmac TARGET_VERSION This macro is a C statement to print on @code{stderr} a string describing the particular machine description choice. Every machine description should define @code{TARGET_VERSION}. For example: @@ -785,9 +844,9 @@ description should define @code{TARGET_VERSION}. For example: fprintf (stderr, " (68k, MIT syntax)"); #endif @end smallexample +@end defmac -@findex OVERRIDE_OPTIONS -@item OVERRIDE_OPTIONS +@defmac OVERRIDE_OPTIONS Sometimes certain combinations of command options do not make sense on a particular target machine. You can define a macro @code{OVERRIDE_OPTIONS} to take account of this. This macro, if @@ -796,9 +855,9 @@ parsed. Don't use this macro to turn on various extra optimizations for @option{-O}. That is what @code{OPTIMIZATION_OPTIONS} is for. +@end defmac -@findex OPTIMIZATION_OPTIONS -@item OPTIMIZATION_OPTIONS (@var{level}, @var{size}) +@defmac OPTIMIZATION_OPTIONS (@var{level}, @var{size}) Some machines may desire to change what optimizations are performed for various optimization levels. This macro, if defined, is executed once just after the optimization level is determined and before the remainder @@ -818,13 +877,13 @@ machine-specific optimizations. @strong{Do not examine @code{write_symbols} in this macro!} The debugging options are not supposed to alter the generated code. +@end defmac -@findex CAN_DEBUG_WITHOUT_FP -@item CAN_DEBUG_WITHOUT_FP +@defmac CAN_DEBUG_WITHOUT_FP Define this macro if debugging can be performed even without a frame pointer. If this macro is defined, GCC will turn on the @option{-fomit-frame-pointer} option whenever @option{-O} is specified. -@end table +@end defmac @node Per-Function Data @section Defining data structures for per-function information. @@ -863,30 +922,24 @@ the saving and restoring of the target specific information. Since the single data area approach is no longer used, these pointers are no longer supported. -The macro and function pointers are described below. - -@table @code -@findex INIT_EXPANDERS -@item INIT_EXPANDERS +@defmac INIT_EXPANDERS Macro called to initialize any target specific information. This macro is called once per function, before generation of any RTL has begun. The intention of this macro is to allow the initialization of the -function pointers below. +function pointer @code{init_machine_status}. +@end defmac -@findex init_machine_status -@item init_machine_status -This is a @code{void (*)(struct function *)} function pointer. If this -pointer is non-@code{NULL} it will be called once per function, before function -compilation starts, in order to allow the target to perform any target -specific initialization of the @code{struct function} structure. It is -intended that this would be used to initialize the @code{machine} of -that structure. +@deftypevar {void (*)(struct function *)} init_machine_status +If this function pointer is non-@code{NULL} it will be called once per +function, before function compilation starts, in order to allow the +target to perform any target specific initialization of the +@code{struct function} structure. It is intended that this would be +used to initialize the @code{machine} of that structure. @code{struct machine_function} structures are expected to be freed by GC. Generally, any memory that they reference must be allocated by using @code{ggc_alloc}, including the structure itself. - -@end table +@end deftypevar @node Storage Layout @section Storage Layout @@ -897,9 +950,7 @@ alignments measured in bits do not need to be constant. They can be C expressions that refer to static variables, such as the @code{target_flags}. @xref{Run-time Target}. -@table @code -@findex BITS_BIG_ENDIAN -@item BITS_BIG_ENDIAN +@defmac BITS_BIG_ENDIAN Define this macro to have the value 1 if the most significant bit in a byte has the lowest number; otherwise define it to have the value zero. This means that bit-field instructions count from the most significant @@ -909,29 +960,29 @@ macro need not be a constant. This macro does not affect the way structure fields are packed into bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. +@end defmac -@findex BYTES_BIG_ENDIAN -@item BYTES_BIG_ENDIAN +@defmac BYTES_BIG_ENDIAN Define this macro to have the value 1 if the most significant byte in a word has the lowest number. This macro need not be a constant. +@end defmac -@findex WORDS_BIG_ENDIAN -@item WORDS_BIG_ENDIAN +@defmac WORDS_BIG_ENDIAN Define this macro to have the value 1 if, in a multiword object, the most significant word has the lowest number. This applies to both memory locations and registers; GCC fundamentally assumes that the order of words in memory is the same as the order in registers. This macro need not be a constant. +@end defmac -@findex LIBGCC2_WORDS_BIG_ENDIAN -@item LIBGCC2_WORDS_BIG_ENDIAN +@defmac LIBGCC2_WORDS_BIG_ENDIAN Define this macro if @code{WORDS_BIG_ENDIAN} is not constant. This must be a constant value with the same meaning as @code{WORDS_BIG_ENDIAN}, which will be used only when compiling @file{libgcc2.c}. Typically the value will be set based on preprocessor defines. +@end defmac -@findex FLOAT_WORDS_BIG_ENDIAN -@item FLOAT_WORDS_BIG_ENDIAN +@defmac FLOAT_WORDS_BIG_ENDIAN Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or @code{TFmode} floating point numbers are stored in memory with the word containing the sign bit at the lowest address; otherwise define it to @@ -939,42 +990,42 @@ have the value 0. This macro need not be a constant. You need not define this macro if the ordering is the same as for multi-word integers. +@end defmac -@findex BITS_PER_UNIT -@item BITS_PER_UNIT +@defmac BITS_PER_UNIT Define this macro to be the number of bits in an addressable storage unit (byte). If you do not define this macro the default is 8. +@end defmac -@findex BITS_PER_WORD -@item BITS_PER_WORD +@defmac BITS_PER_WORD Number of bits in a word. If you do not define this macro, the default is @code{BITS_PER_UNIT * UNITS_PER_WORD}. +@end defmac -@findex MAX_BITS_PER_WORD -@item MAX_BITS_PER_WORD +@defmac MAX_BITS_PER_WORD Maximum number of bits in a word. If this is undefined, the default is @code{BITS_PER_WORD}. Otherwise, it is the constant value that is the largest value that @code{BITS_PER_WORD} can have at run-time. +@end defmac -@findex UNITS_PER_WORD -@item UNITS_PER_WORD +@defmac UNITS_PER_WORD Number of storage units in a word; normally 4. +@end defmac -@findex MIN_UNITS_PER_WORD -@item MIN_UNITS_PER_WORD +@defmac MIN_UNITS_PER_WORD Minimum number of units in a word. If this is undefined, the default is @code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the smallest value that @code{UNITS_PER_WORD} can have at run-time. +@end defmac -@findex POINTER_SIZE -@item POINTER_SIZE +@defmac POINTER_SIZE Width of a pointer, in bits. You must specify a value no wider than the width of @code{Pmode}. If it is not equal to the width of @code{Pmode}, you must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify a value the default is @code{BITS_PER_WORD}. +@end defmac -@findex POINTERS_EXTEND_UNSIGNED -@item POINTERS_EXTEND_UNSIGNED +@defmac POINTERS_EXTEND_UNSIGNED A C expression whose value is greater than zero if pointers that need to be extended from being @code{POINTER_SIZE} bits wide to @code{Pmode} are to be zero-extended and zero if they are to be sign-extended. If the value @@ -983,9 +1034,9 @@ extends a pointer from @code{POINTER_SIZE} to @code{Pmode}. You need not define this macro if the @code{POINTER_SIZE} is equal to the width of @code{Pmode}. +@end defmac -@findex PROMOTE_MODE -@item PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) +@defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) A macro to update @var{m} and @var{unsignedp} when an object whose type is @var{type} and which has the specified mode and signedness is to be stored in a register. This macro is only called when @var{type} is a @@ -1006,52 +1057,53 @@ sign-extend the result to 64 bits. On such machines, set @var{unsignedp} according to which kind of extension is more efficient. Do not define this macro if it would never modify @var{m}. +@end defmac -@findex PROMOTE_FUNCTION_ARGS -@item PROMOTE_FUNCTION_ARGS -Define this macro if the promotion described by @code{PROMOTE_MODE} -should also be done for outgoing function arguments. +@deftypefn {Target Hook} bool TARGET_PROMOTE_FUNCTION_ARGS (tree @var{fntype}) +This target hook should return @code{true} if the promotion described by +@code{PROMOTE_MODE} should also be done for outgoing function arguments. +@end deftypefn -@findex PROMOTE_FUNCTION_RETURN -@item PROMOTE_FUNCTION_RETURN -Define this macro if the promotion described by @code{PROMOTE_MODE} -should also be done for the return value of functions. +@deftypefn {Target Hook} bool TARGET_PROMOTE_FUNCTION_RETURN (tree @var{fntype}) +This target hook should return @code{true} if the promotion described by +@code{PROMOTE_MODE} should also be done for the return value of +functions. -If this macro is defined, @code{FUNCTION_VALUE} must perform the same -promotions done by @code{PROMOTE_MODE}. +If this target hook returns @code{true}, @code{FUNCTION_VALUE} must +perform the same promotions done by @code{PROMOTE_MODE}. +@end deftypefn -@findex PROMOTE_FOR_CALL_ONLY -@item PROMOTE_FOR_CALL_ONLY +@defmac PROMOTE_FOR_CALL_ONLY Define this macro if the promotion described by @code{PROMOTE_MODE} should @emph{only} be performed for outgoing function arguments or -function return values, as specified by @code{PROMOTE_FUNCTION_ARGS} -and @code{PROMOTE_FUNCTION_RETURN}, respectively. +function return values, as specified by @code{TARGET_PROMOTE_FUNCTION_ARGS} +and @code{TARGET_PROMOTE_FUNCTION_RETURN}, respectively. +@end defmac -@findex PARM_BOUNDARY -@item PARM_BOUNDARY +@defmac PARM_BOUNDARY Normal alignment required for function parameters on the stack, in bits. All stack parameters receive at least this much alignment regardless of data type. On most machines, this is the same as the size of an integer. +@end defmac -@findex STACK_BOUNDARY -@item STACK_BOUNDARY +@defmac STACK_BOUNDARY Define this macro to the minimum alignment enforced by hardware for the stack pointer on this machine. The definition is a C expression for the desired alignment (measured in bits). This value is used as a default if @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines, this should be the same as @code{PARM_BOUNDARY}. +@end defmac -@findex PREFERRED_STACK_BOUNDARY -@item PREFERRED_STACK_BOUNDARY +@defmac PREFERRED_STACK_BOUNDARY Define this macro if you wish to preserve a certain alignment for the stack pointer, greater than what the hardware enforces. The definition is a C expression for the desired alignment (measured in bits). This macro must evaluate to a value equal to or larger than @code{STACK_BOUNDARY}. +@end defmac -@findex FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN -@item FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN +@defmac FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN A C expression that evaluates true if @code{PREFERRED_STACK_BOUNDARY} is not guaranteed by the runtime and we should emit code to align the stack at the beginning of @code{main}. @@ -1061,47 +1113,47 @@ If @code{PUSH_ROUNDING} is not defined, the stack will always be aligned to the specified boundary. If @code{PUSH_ROUNDING} is defined and specifies a less strict alignment than @code{PREFERRED_STACK_BOUNDARY}, the stack may be momentarily unaligned while pushing arguments. +@end defmac -@findex FUNCTION_BOUNDARY -@item FUNCTION_BOUNDARY +@defmac FUNCTION_BOUNDARY Alignment required for a function entry point, in bits. +@end defmac -@findex BIGGEST_ALIGNMENT -@item BIGGEST_ALIGNMENT +@defmac BIGGEST_ALIGNMENT Biggest alignment that any data type can require on this machine, in bits. +@end defmac -@findex MINIMUM_ATOMIC_ALIGNMENT -@item MINIMUM_ATOMIC_ALIGNMENT +@defmac MINIMUM_ATOMIC_ALIGNMENT If defined, the smallest alignment, in bits, that can be given to an object that can be referenced in one operation, without disturbing any nearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger on machines that don't have byte or half-word store operations. +@end defmac -@findex BIGGEST_FIELD_ALIGNMENT -@item BIGGEST_FIELD_ALIGNMENT +@defmac BIGGEST_FIELD_ALIGNMENT Biggest alignment that any structure or union field can require on this machine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for structure and union fields only, unless the field alignment has been set by the @code{__attribute__ ((aligned (@var{n})))} construct. +@end defmac -@findex ADJUST_FIELD_ALIGN -@item ADJUST_FIELD_ALIGN (@var{field}, @var{computed}) +@defmac ADJUST_FIELD_ALIGN (@var{field}, @var{computed}) An expression for the alignment of a structure field @var{field} if the alignment computed in the usual way (including applying of @code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the alignment) is @var{computed}. It overrides alignment only if the field alignment has not been set by the @code{__attribute__ ((aligned (@var{n})))} construct. +@end defmac -@findex MAX_OFILE_ALIGNMENT -@item MAX_OFILE_ALIGNMENT +@defmac MAX_OFILE_ALIGNMENT Biggest alignment supported by the object file format of this machine. Use this macro to limit the alignment which can be specified using the @code{__attribute__ ((aligned (@var{n})))} construct. If not defined, the default value is @code{BIGGEST_ALIGNMENT}. +@end defmac -@findex DATA_ALIGNMENT -@item DATA_ALIGNMENT (@var{type}, @var{basic-align}) +@defmac DATA_ALIGNMENT (@var{type}, @var{basic-align}) If defined, a C expression to compute the alignment for a variable in the static store. @var{type} is the data type, and @var{basic-align} is the alignment that the object would ordinarily have. The value of this @@ -1114,9 +1166,9 @@ One use of this macro is to increase alignment of medium-size data to make it all fit in fewer cache lines. Another is to cause character arrays to be word-aligned so that @code{strcpy} calls that copy constants to character arrays can be done inline. +@end defmac -@findex CONSTANT_ALIGNMENT -@item CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) +@defmac CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) If defined, a C expression to compute the alignment given to a constant that is being placed in memory. @var{constant} is the constant and @var{basic-align} is the alignment that the object would ordinarily @@ -1128,9 +1180,9 @@ If this macro is not defined, then @var{basic-align} is used. The typical use of this macro is to increase alignment for string constants to be word aligned so that @code{strcpy} calls that copy constants can be done inline. +@end defmac -@findex LOCAL_ALIGNMENT -@item LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) +@defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) If defined, a C expression to compute the alignment for a variable in the local store. @var{type} is the data type, and @var{basic-align} is the alignment that the object would ordinarily have. The value of this @@ -1140,45 +1192,46 @@ If this macro is not defined, then @var{basic-align} is used. One use of this macro is to increase alignment of medium-size data to make it all fit in fewer cache lines. +@end defmac -@findex EMPTY_FIELD_BOUNDARY -@item EMPTY_FIELD_BOUNDARY +@defmac EMPTY_FIELD_BOUNDARY Alignment in bits to be given to a structure bit-field that follows an empty field such as @code{int : 0;}. -Note that @code{PCC_BITFIELD_TYPE_MATTERS} also affects the alignment -that results from an empty field. +If @code{PCC_BITFIELD_TYPE_MATTERS} is true, it overrides this macro. +@end defmac -@findex STRUCTURE_SIZE_BOUNDARY -@item STRUCTURE_SIZE_BOUNDARY +@defmac STRUCTURE_SIZE_BOUNDARY Number of bits which any structure or union's size must be a multiple of. Each structure or union's size is rounded up to a multiple of this. If you do not define this macro, the default is the same as @code{BITS_PER_UNIT}. +@end defmac -@findex STRICT_ALIGNMENT -@item STRICT_ALIGNMENT +@defmac STRICT_ALIGNMENT Define this macro to be the value 1 if instructions will fail to work if given data not on the nominal alignment. If instructions will merely go slower in that case, define this macro as 0. +@end defmac -@findex PCC_BITFIELD_TYPE_MATTERS -@item PCC_BITFIELD_TYPE_MATTERS +@defmac PCC_BITFIELD_TYPE_MATTERS Define this if you wish to imitate the way many other C compilers handle alignment of bit-fields and the structures that contain them. -The behavior is that the type written for a bit-field (@code{int}, -@code{short}, or other integer type) imposes an alignment for the -entire structure, as if the structure really did contain an ordinary -field of that type. In addition, the bit-field is placed within the -structure so that it would fit within such a field, not crossing a -boundary for it. +The behavior is that the type written for a named bit-field (@code{int}, +@code{short}, or other integer type) imposes an alignment for the entire +structure, as if the structure really did contain an ordinary field of +that type. In addition, the bit-field is placed within the structure so +that it would fit within such a field, not crossing a boundary for it. + +Thus, on most machines, a named bit-field whose type is written as +@code{int} would not cross a four-byte boundary, and would force +four-byte alignment for the whole structure. (The alignment used may +not be four bytes; it is controlled by the other alignment parameters.) -Thus, on most machines, a bit-field whose type is written as @code{int} -would not cross a four-byte boundary, and would force four-byte -alignment for the whole structure. (The alignment used may not be four -bytes; it is controlled by the other alignment parameters.) +An unnamed bit-field will not affect the alignment of the containing +structure. If the macro is defined, its definition should be a C expression; a nonzero value for the expression enables this behavior. @@ -1200,7 +1253,7 @@ If your aim is to make GCC use the same conventions for laying out bit-fields as are used by another compiler, here is how to investigate what the other compiler does. Compile and run this program: -@example +@smallexample struct foo1 @{ char x; @@ -1223,18 +1276,18 @@ main () sizeof (struct foo2)); exit (0); @} -@end example +@end smallexample If this prints 2 and 5, then the compiler's behavior is what you would get from @code{PCC_BITFIELD_TYPE_MATTERS}. +@end defmac -@findex BITFIELD_NBYTES_LIMITED -@item BITFIELD_NBYTES_LIMITED +@defmac BITFIELD_NBYTES_LIMITED Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited to aligning a bit-field within the structure. +@end defmac -@findex MEMBER_TYPE_FORCES_BLK -@item MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode}) +@defmac MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode}) Return 1 if a structure or array containing @var{field} should be accessed using @code{BLKMODE}. @@ -1246,24 +1299,9 @@ retain the field's mode. Normally, this is not needed. See the file @file{c4x.h} for an example of how to use this macro to prevent a structure having a floating point field from being accessed in an integer mode. +@end defmac -@findex ROUND_TYPE_SIZE -@item ROUND_TYPE_SIZE (@var{type}, @var{computed}, @var{specified}) -Define this macro as an expression for the overall size of a type -(given by @var{type} as a tree node) when the size computed in the -usual way is @var{computed} and the alignment is @var{specified}. - -The default is to round @var{computed} up to a multiple of @var{specified}. - -@findex ROUND_TYPE_SIZE_UNIT -@item ROUND_TYPE_SIZE_UNIT (@var{type}, @var{computed}, @var{specified}) -Similar to @code{ROUND_TYPE_SIZE}, but sizes and alignments are -specified in units (bytes). If you define @code{ROUND_TYPE_SIZE}, -you must also define this macro and they must be defined consistently -with each other. - -@findex ROUND_TYPE_ALIGN -@item ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) +@defmac ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) Define this macro as an expression for the alignment of a type (given by @var{type} as a tree node) if the alignment computed in the usual way is @var{computed} and the alignment explicitly specified was @@ -1271,23 +1309,23 @@ way is @var{computed} and the alignment explicitly specified was The default is to use @var{specified} if it is larger; otherwise, use the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} +@end defmac -@findex MAX_FIXED_MODE_SIZE -@item MAX_FIXED_MODE_SIZE +@defmac MAX_FIXED_MODE_SIZE An integer expression for the size in bits of the largest integer machine mode that should actually be used. All integer machine modes of this size or smaller can be used for structures and unions with the appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE (DImode)} is assumed. +@end defmac -@findex VECTOR_MODE_SUPPORTED_P -@item VECTOR_MODE_SUPPORTED_P(@var{mode}) +@defmac VECTOR_MODE_SUPPORTED_P (@var{mode}) Define this macro to be nonzero if the port is prepared to handle insns involving vector mode @var{mode}. At the very least, it must have move patterns for this mode. +@end defmac -@findex STACK_SAVEAREA_MODE -@item STACK_SAVEAREA_MODE (@var{save_level}) +@defmac STACK_SAVEAREA_MODE (@var{save_level}) If defined, an expression of type @code{enum machine_mode} that specifies the mode of the save area operand of a @code{save_stack_@var{level}} named pattern (@pxref{Standard Names}). @@ -1299,9 +1337,9 @@ You need not define this macro if it always returns @code{Pmode}. You would most commonly define this macro if the @code{save_stack_@var{level}} patterns need to support both a 32- and a 64-bit mode. +@end defmac -@findex STACK_SIZE_MODE -@item STACK_SIZE_MODE +@defmac STACK_SIZE_MODE If defined, an expression of type @code{enum machine_mode} that specifies the mode of the size increment operand of an @code{allocate_stack} named pattern (@pxref{Standard Names}). @@ -1309,45 +1347,37 @@ specifies the mode of the size increment operand of an You need not define this macro if it always returns @code{word_mode}. You would most commonly define this macro if the @code{allocate_stack} pattern needs to support both a 32- and a 64-bit mode. +@end defmac -@findex TARGET_FLOAT_FORMAT -@item TARGET_FLOAT_FORMAT +@defmac TARGET_FLOAT_FORMAT A code distinguishing the floating point format of the target machine. -There are five defined values: +There are four defined values: -@table @code -@findex IEEE_FLOAT_FORMAT +@ftable @code @item IEEE_FLOAT_FORMAT This code indicates IEEE floating point. It is the default; there is no -need to define this macro when the format is IEEE@. +need to define @code{TARGET_FLOAT_FORMAT} when the format is IEEE@. -@findex VAX_FLOAT_FORMAT @item VAX_FLOAT_FORMAT This code indicates the ``F float'' (for @code{float}) and ``D float'' or ``G float'' formats (for @code{double}) used on the VAX and PDP-11@. -@findex IBM_FLOAT_FORMAT @item IBM_FLOAT_FORMAT This code indicates the format used on the IBM System/370. -@findex C4X_FLOAT_FORMAT @item C4X_FLOAT_FORMAT This code indicates the format used on the TMS320C3x/C4x. +@end ftable -@findex UNKNOWN_FLOAT_FORMAT -@item UNKNOWN_FLOAT_FORMAT -This code indicates any other format. -@end table - -If any other -formats are actually in use on supported machines, new codes should be -defined for them. +If your target uses a floating point format other than these, you must +define a new @var{name}_FLOAT_FORMAT code for it, and add support for +it to @file{real.c}. The ordering of the component words of floating point values stored in memory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN}. +@end defmac -@findex MODE_HAS_NANS -@item MODE_HAS_NANS (@var{mode}) +@defmac MODE_HAS_NANS (@var{mode}) When defined, this macro should be true if @var{mode} has a NaN representation. The compiler assumes that NaNs are not equal to anything (including themselves) and that addition, subtraction, @@ -1356,16 +1386,16 @@ NaN@. By default, this macro is true if @var{mode} is a floating-point mode and the target floating-point format is IEEE@. +@end defmac -@findex MODE_HAS_INFINITIES -@item MODE_HAS_INFINITIES (@var{mode}) +@defmac MODE_HAS_INFINITIES (@var{mode}) This macro should be true if @var{mode} can represent infinity. At present, the compiler uses this macro to decide whether @samp{x - x} is always defined. By default, the macro is true when @var{mode} is a floating-point mode and the target format is IEEE@. +@end defmac -@findex MODE_HAS_SIGNED_ZEROS -@item MODE_HAS_SIGNED_ZEROS (@var{mode}) +@defmac MODE_HAS_SIGNED_ZEROS (@var{mode}) True if @var{mode} distinguishes between positive and negative zero. The rules are expected to follow the IEEE standard: @@ -1385,9 +1415,9 @@ of the operands is negative. The default definition is true if @var{mode} is a floating-point mode and the target format is IEEE@. +@end defmac -@findex MODE_HAS_SIGN_DEPENDENT_ROUNDING -@item MODE_HAS_SIGN_DEPENDENT_ROUNDING (@var{mode}) +@defmac MODE_HAS_SIGN_DEPENDENT_ROUNDING (@var{mode}) If defined, this macro should be true for @var{mode} if it has at least one rounding mode in which @samp{x} and @samp{-x} can be rounded to numbers of different magnitude. Two such modes are @@ -1395,9 +1425,9 @@ towards @minus{}infinity and towards +infinity. The default definition of this macro is true if @var{mode} is a floating-point mode and the target format is IEEE@. +@end defmac -@findex ROUND_TOWARDS_ZERO -@item ROUND_TOWARDS_ZERO +@defmac ROUND_TOWARDS_ZERO If defined, this macro should be true if the prevailing rounding mode is towards zero. A true value has the following effects: @@ -1421,9 +1451,9 @@ primary rounding mode is towards zero, library functions like parser should behave like the target's @code{strtod} where possible. Not defining this macro is equivalent to returning zero. +@end defmac -@findex LARGEST_EXPONENT_IS_NORMAL -@item LARGEST_EXPONENT_IS_NORMAL (@var{size}) +@defmac LARGEST_EXPONENT_IS_NORMAL (@var{size}) This macro should return true if floats with @var{size} bits do not have a NaN or infinity representation, but use the largest exponent for normal numbers instead. @@ -1434,7 +1464,15 @@ It also affects the way @file{libgcc.a} and @file{real.c} emulate floating-point arithmetic. The default definition of this macro returns false for all sizes. -@end table +@end defmac + +@deftypefn {Target Hook} bool TARGET_VECTOR_OPAQUE_P (tree @var{type}) +This target hook should return @code{true} a vector is opaque. That +is, if no cast is needed when copying a vector value of type +@var{type} into another vector lvalue of the same size. Vector opaque +types cannot be initialized. The default is that there are no such +types. +@end deftypefn @deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (tree @var{record_type}) This target hook returns @code{true} if bit-fields in the given @@ -1472,116 +1510,115 @@ basic data types used in programs being compiled. Unlike the macros in the previous section, these apply to specific features of C and related languages, rather than to fundamental aspects of storage layout. -@table @code -@findex INT_TYPE_SIZE -@item INT_TYPE_SIZE +@defmac INT_TYPE_SIZE A C expression for the size in bits of the type @code{int} on the target machine. If you don't define this, the default is one word. +@end defmac -@findex SHORT_TYPE_SIZE -@item SHORT_TYPE_SIZE +@defmac SHORT_TYPE_SIZE A C expression for the size in bits of the type @code{short} on the target machine. If you don't define this, the default is half a word. (If this would be less than one storage unit, it is rounded up to one unit.) +@end defmac -@findex LONG_TYPE_SIZE -@item LONG_TYPE_SIZE +@defmac LONG_TYPE_SIZE A C expression for the size in bits of the type @code{long} on the target machine. If you don't define this, the default is one word. +@end defmac -@findex ADA_LONG_TYPE_SIZE -@item ADA_LONG_TYPE_SIZE +@defmac ADA_LONG_TYPE_SIZE On some machines, the size used for the Ada equivalent of the type @code{long} by a native Ada compiler differs from that used by C. In that situation, define this macro to be a C expression to be used for the size of that type. If you don't define this, the default is the value of @code{LONG_TYPE_SIZE}. +@end defmac -@findex MAX_LONG_TYPE_SIZE -@item MAX_LONG_TYPE_SIZE +@defmac MAX_LONG_TYPE_SIZE Maximum number for the size in bits of the type @code{long} on the target machine. If this is undefined, the default is @code{LONG_TYPE_SIZE}. Otherwise, it is the constant value that is the largest value that @code{LONG_TYPE_SIZE} can have at run-time. This is used in @code{cpp}. +@end defmac -@findex LONG_LONG_TYPE_SIZE -@item LONG_LONG_TYPE_SIZE +@defmac LONG_LONG_TYPE_SIZE A C expression for the size in bits of the type @code{long long} on the target machine. If you don't define this, the default is two words. If you want to support GNU Ada on your machine, the value of this macro must be at least 64. +@end defmac -@findex CHAR_TYPE_SIZE -@item CHAR_TYPE_SIZE +@defmac CHAR_TYPE_SIZE A C expression for the size in bits of the type @code{char} on the target machine. If you don't define this, the default is @code{BITS_PER_UNIT}. +@end defmac -@findex BOOL_TYPE_SIZE -@item BOOL_TYPE_SIZE +@defmac BOOL_TYPE_SIZE A C expression for the size in bits of the C++ type @code{bool} and C99 type @code{_Bool} on the target machine. If you don't define this, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}. +@end defmac -@findex FLOAT_TYPE_SIZE -@item FLOAT_TYPE_SIZE +@defmac FLOAT_TYPE_SIZE A C expression for the size in bits of the type @code{float} on the target machine. If you don't define this, the default is one word. +@end defmac -@findex DOUBLE_TYPE_SIZE -@item DOUBLE_TYPE_SIZE +@defmac DOUBLE_TYPE_SIZE A C expression for the size in bits of the type @code{double} on the target machine. If you don't define this, the default is two words. +@end defmac -@findex LONG_DOUBLE_TYPE_SIZE -@item LONG_DOUBLE_TYPE_SIZE +@defmac LONG_DOUBLE_TYPE_SIZE A C expression for the size in bits of the type @code{long double} on the target machine. If you don't define this, the default is two words. +@end defmac -@findex MAX_LONG_DOUBLE_TYPE_SIZE +@defmac MAX_LONG_DOUBLE_TYPE_SIZE Maximum number for the size in bits of the type @code{long double} on the target machine. If this is undefined, the default is @code{LONG_DOUBLE_TYPE_SIZE}. Otherwise, it is the constant value that is the largest value that @code{LONG_DOUBLE_TYPE_SIZE} can have at run-time. This is used in @code{cpp}. +@end defmac -@findex TARGET_FLT_EVAL_METHOD -@item TARGET_FLT_EVAL_METHOD +@defmac TARGET_FLT_EVAL_METHOD A C expression for the value for @code{FLT_EVAL_METHOD} in @file{float.h}, assuming, if applicable, that the floating-point control word is in its default state. If you do not define this macro the value of @code{FLT_EVAL_METHOD} will be zero. +@end defmac -@findex WIDEST_HARDWARE_FP_SIZE -@item WIDEST_HARDWARE_FP_SIZE +@defmac WIDEST_HARDWARE_FP_SIZE A C expression for the size in bits of the widest floating-point format supported by the hardware. If you define this macro, you must specify a value less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}. If you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE} is the default. +@end defmac -@findex DEFAULT_SIGNED_CHAR -@item DEFAULT_SIGNED_CHAR +@defmac DEFAULT_SIGNED_CHAR An expression whose value is 1 or 0, according to whether the type @code{char} should be signed or unsigned by default. The user can always override this default with the options @option{-fsigned-char} and @option{-funsigned-char}. +@end defmac -@findex DEFAULT_SHORT_ENUMS -@item DEFAULT_SHORT_ENUMS +@defmac DEFAULT_SHORT_ENUMS A C expression to determine whether to give an @code{enum} type only as many bytes as it takes to represent the range of possible values of that type. A nonzero value means to do that; a zero value means all @code{enum} types should be allocated like @code{int}. If you don't define the macro, the default is 0. +@end defmac -@findex SIZE_TYPE -@item SIZE_TYPE +@defmac SIZE_TYPE A C expression for a string describing the name of the data type to use for size values. The typedef name @code{size_t} is defined using the contents of the string. @@ -1596,49 +1633,49 @@ crash on startup. If you don't define this macro, the default is @code{"long unsigned int"}. +@end defmac -@findex PTRDIFF_TYPE -@item PTRDIFF_TYPE +@defmac PTRDIFF_TYPE A C expression for a string describing the name of the data type to use for the result of subtracting two pointers. The typedef name @code{ptrdiff_t} is defined using the contents of the string. See @code{SIZE_TYPE} above for more information. If you don't define this macro, the default is @code{"long int"}. +@end defmac -@findex WCHAR_TYPE -@item WCHAR_TYPE +@defmac WCHAR_TYPE A C expression for a string describing the name of the data type to use for wide characters. The typedef name @code{wchar_t} is defined using the contents of the string. See @code{SIZE_TYPE} above for more information. If you don't define this macro, the default is @code{"int"}. +@end defmac -@findex WCHAR_TYPE_SIZE -@item WCHAR_TYPE_SIZE +@defmac WCHAR_TYPE_SIZE A C expression for the size in bits of the data type for wide characters. This is used in @code{cpp}, which cannot make use of @code{WCHAR_TYPE}. +@end defmac -@findex MAX_WCHAR_TYPE_SIZE -@item MAX_WCHAR_TYPE_SIZE +@defmac MAX_WCHAR_TYPE_SIZE Maximum number for the size in bits of the data type for wide characters. If this is undefined, the default is @code{WCHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the largest value that @code{WCHAR_TYPE_SIZE} can have at run-time. This is used in @code{cpp}. +@end defmac -@findex GCOV_TYPE_SIZE -@item GCOV_TYPE_SIZE +@defmac GCOV_TYPE_SIZE A C expression for the size in bits of the type used for gcov counters on the target machine. If you don't define this, the default is one @code{LONG_TYPE_SIZE} in case it is greater or equal to 64-bit and @code{LONG_LONG_TYPE_SIZE} otherwise. You may want to re-define the type to ensure atomicity for counters in multithreaded programs. +@end defmac -@findex WINT_TYPE -@item WINT_TYPE +@defmac WINT_TYPE A C expression for a string describing the name of the data type to use for wide characters passed to @code{printf} and returned from @code{getwc}. The typedef name @code{wint_t} is defined using the @@ -1646,9 +1683,9 @@ contents of the string. See @code{SIZE_TYPE} above for more information. If you don't define this macro, the default is @code{"unsigned int"}. +@end defmac -@findex INTMAX_TYPE -@item INTMAX_TYPE +@defmac INTMAX_TYPE A C expression for a string describing the name of the data type that can represent any value of any standard or extended signed integer type. The typedef name @code{intmax_t} is defined using the contents of the @@ -1657,9 +1694,9 @@ string. See @code{SIZE_TYPE} above for more information. If you don't define this macro, the default is the first of @code{"int"}, @code{"long int"}, or @code{"long long int"} that has as much precision as @code{long long int}. +@end defmac -@findex UINTMAX_TYPE -@item UINTMAX_TYPE +@defmac UINTMAX_TYPE A C expression for a string describing the name of the data type that can represent any value of any standard or extended unsigned integer type. The typedef name @code{uintmax_t} is defined using the contents @@ -1669,13 +1706,13 @@ If you don't define this macro, the default is the first of @code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long unsigned int"} that has as much precision as @code{long long unsigned int}. +@end defmac -@findex TARGET_PTRMEMFUNC_VBIT_LOCATION -@item TARGET_PTRMEMFUNC_VBIT_LOCATION +@defmac TARGET_PTRMEMFUNC_VBIT_LOCATION The C++ compiler represents a pointer-to-member-function with a struct that looks like: -@example +@smallexample struct @{ union @{ void (*fn)(); @@ -1683,7 +1720,7 @@ that looks like: @}; ptrdiff_t delta; @}; -@end example +@end smallexample @noindent The C++ compiler must use one bit to indicate whether the function that @@ -1708,9 +1745,9 @@ In general, you should not have to define this macro. On architectures in which function addresses are always even, according to @code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to @code{ptrmemfunc_vbit_in_pfn}. +@end defmac -@findex TARGET_VTABLE_USES_DESCRIPTORS -@item TARGET_VTABLE_USES_DESCRIPTORS +@defmac TARGET_VTABLE_USES_DESCRIPTORS Normally, the C++ compiler uses function pointers in vtables. This macro allows the target to change to use ``function descriptors'' instead. Function descriptors are found on targets for whom a @@ -1720,21 +1757,21 @@ pointer to which the function's data is relative. If vtables are used, the value of this macro should be the number of words that the function descriptor occupies. +@end defmac -@findex TARGET_VTABLE_ENTRY_ALIGN -@item TARGET_VTABLE_ENTRY_ALIGN +@defmac TARGET_VTABLE_ENTRY_ALIGN By default, the vtable entries are void pointers, the so the alignment is the same as pointer alignment. The value of this macro specifies the alignment of the vtable entry in bits. It should be defined only when special alignment is necessary. */ +@end defmac -@findex TARGET_VTABLE_DATA_ENTRY_DISTANCE -@item TARGET_VTABLE_DATA_ENTRY_DISTANCE +@defmac TARGET_VTABLE_DATA_ENTRY_DISTANCE There are a few non-descriptor entries in the vtable at offsets below zero. If these entries must be padded (say, to preserve the alignment specified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number of words in each data entry. -@end table +@end defmac @node Escape Sequences @section Target Character Escape Sequences @@ -1742,38 +1779,30 @@ of words in each data entry. By default, GCC assumes that the C character escape sequences take on their ASCII values for the target. If this is not correct, you must -explicitly define all of the macros below. +explicitly define all of the macros below. All of them must evaluate +to constants; they are used in @code{case} statements. -@table @code @findex TARGET_BELL -@item TARGET_BELL -A C constant expression for the integer value for escape sequence -@samp{\a}. - +@findex TARGET_CR @findex TARGET_ESC -@item TARGET_ESC -A C constant expression for the integer value of the target escape -character. As an extension, GCC evaluates the escape sequences -@samp{\e} and @samp{\E} to this. - -@findex TARGET_TAB -@findex TARGET_BS +@findex TARGET_FF @findex TARGET_NEWLINE -@item TARGET_BS -@itemx TARGET_TAB -@itemx TARGET_NEWLINE -C constant expressions for the integer values for escape sequences -@samp{\b}, @samp{\t} and @samp{\n}. - +@findex TARGET_TAB @findex TARGET_VT -@findex TARGET_FF -@findex TARGET_CR -@item TARGET_VT -@itemx TARGET_FF -@itemx TARGET_CR -C constant expressions for the integer values for escape sequences -@samp{\v}, @samp{\f} and @samp{\r}. -@end table +@multitable {@code{TARGET_NEWLINE}} {Escape} {ASCII character} +@item Macro @tab Escape @tab ASCII character +@item @code{TARGET_BELL} @tab @kbd{\a} @tab @code{07}, @code{BEL} +@item @code{TARGET_CR} @tab @kbd{\r} @tab @code{0D}, @code{CR} +@item @code{TARGET_ESC} @tab @kbd{\e}, @kbd{\E} @tab @code{1B}, @code{ESC} +@item @code{TARGET_FF} @tab @kbd{\f} @tab @code{0C}, @code{FF} +@item @code{TARGET_NEWLINE} @tab @kbd{\n} @tab @code{0A}, @code{LF} +@item @code{TARGET_TAB} @tab @kbd{\t} @tab @code{09}, @code{HT} +@item @code{TARGET_VT} @tab @kbd{\v} @tab @code{0B}, @code{VT} +@end multitable + +@noindent +Note that the @kbd{\e} and @kbd{\E} escapes are GNU extensions, not +part of the C standard. @node Registers @section Register Usage @@ -1802,16 +1831,14 @@ For returning values in registers, see @ref{Scalar Return}. @c prevent bad page break with this line Registers have various characteristics. -@table @code -@findex FIRST_PSEUDO_REGISTER -@item FIRST_PSEUDO_REGISTER +@defmac FIRST_PSEUDO_REGISTER Number of hardware registers known to the compiler. They receive numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first pseudo register's number really is assigned the number @code{FIRST_PSEUDO_REGISTER}. +@end defmac -@item FIXED_REGISTERS -@findex FIXED_REGISTERS +@defmac FIXED_REGISTERS @cindex fixed register An initializer that says which registers are used for fixed purposes all throughout the compiled code and are therefore not available for @@ -1830,9 +1857,9 @@ the following one, may be overridden at run time either automatically, by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by the user with the command options @option{-ffixed-@var{reg}}, @option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}. +@end defmac -@findex CALL_USED_REGISTERS -@item CALL_USED_REGISTERS +@defmac CALL_USED_REGISTERS @cindex call-used register @cindex call-clobbered register @cindex call-saved register @@ -1845,9 +1872,9 @@ function calls. If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler automatically saves it on function entry and restores it on function exit, if the register is used within the function. +@end defmac -@findex CALL_REALLY_USED_REGISTERS -@item CALL_REALLY_USED_REGISTERS +@defmac CALL_REALLY_USED_REGISTERS @cindex call-used register @cindex call-clobbered register @cindex call-saved register @@ -1856,9 +1883,9 @@ that the entire set of @code{FIXED_REGISTERS} be included. (@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}). This macro is optional. If not specified, it defaults to the value of @code{CALL_USED_REGISTERS}. +@end defmac -@findex HARD_REGNO_CALL_PART_CLOBBERED -@item HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode}) +@defmac HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode}) @cindex call-used register @cindex call-clobbered register @cindex call-saved register @@ -1867,11 +1894,14 @@ value of mode @var{mode} in hard register number @var{regno} across a call without some part of it being clobbered. For most machines this macro need not be defined. It is only required for machines that do not preserve the entire contents of a register across a call. +@end defmac -@findex CONDITIONAL_REGISTER_USAGE @findex fixed_regs @findex call_used_regs -@item CONDITIONAL_REGISTER_USAGE +@findex global_regs +@findex reg_names +@findex reg_class_contents +@defmac CONDITIONAL_REGISTER_USAGE Zero or more C statements that may conditionally modify five variables @code{fixed_regs}, @code{call_used_regs}, @code{global_regs}, @code{reg_names}, and @code{reg_class_contents}, to take into account @@ -1895,53 +1925,52 @@ If the usage of an entire class of registers depends on the target flags, you may indicate this to GCC by using this macro to modify @code{fixed_regs} and @code{call_used_regs} to 1 for each of the registers in the classes which should not be used by GCC@. Also define -the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it +the macro @code{REG_CLASS_FROM_LETTER} / @code{REG_CLASS_FROM_CONSTRAINT} +to return @code{NO_REGS} if it is called with a letter for a class that shouldn't be used. (However, if this class is not included in @code{GENERAL_REGS} and all of the insn patterns whose constraints permit this class are controlled by target switches, then GCC will automatically avoid using these registers when the target switches are opposed to them.) +@end defmac -@findex NON_SAVING_SETJMP -@item NON_SAVING_SETJMP +@defmac NON_SAVING_SETJMP If this macro is defined and has a nonzero value, it means that @code{setjmp} and related functions fail to save the registers, or that @code{longjmp} fails to restore them. To compensate, the compiler avoids putting variables in registers in functions that use @code{setjmp}. +@end defmac -@findex INCOMING_REGNO -@item INCOMING_REGNO (@var{out}) +@defmac INCOMING_REGNO (@var{out}) Define this macro if the target machine has register windows. This C expression returns the register number as seen by the called function corresponding to the register number @var{out} as seen by the calling function. Return @var{out} if register number @var{out} is not an outbound register. +@end defmac -@findex OUTGOING_REGNO -@item OUTGOING_REGNO (@var{in}) +@defmac OUTGOING_REGNO (@var{in}) Define this macro if the target machine has register windows. This C expression returns the register number as seen by the calling function corresponding to the register number @var{in} as seen by the called function. Return @var{in} if register number @var{in} is not an inbound register. +@end defmac -@findex LOCAL_REGNO -@item LOCAL_REGNO (@var{regno}) +@defmac LOCAL_REGNO (@var{regno}) Define this macro if the target machine has register windows. This C expression returns true if the register is call-saved but is in the register window. Unlike most call-saved registers, such registers need not be explicitly restored on function exit or during non-local gotos. +@end defmac -@ignore -@findex PC_REGNUM -@item PC_REGNUM +@defmac PC_REGNUM If the program counter has a register number, define this as that register number. Otherwise, do not define it. -@end ignore -@end table +@end defmac @node Allocation Order @subsection Order of Allocation of Registers @@ -1951,9 +1980,7 @@ register number. Otherwise, do not define it. @c prevent bad page break with this line Registers are allocated in order. -@table @code -@findex REG_ALLOC_ORDER -@item REG_ALLOC_ORDER +@defmac REG_ALLOC_ORDER If defined, an initializer for a vector of integers, containing the numbers of hard registers in the order in which GCC should prefer to use them (from most preferred to least). @@ -1966,9 +1993,9 @@ registers must always be saved and the save-multiple-registers instruction supports only sequences of consecutive registers. On such machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists the highest numbered allocable register first. +@end defmac -@findex ORDER_REGS_FOR_LOCAL_ALLOC -@item ORDER_REGS_FOR_LOCAL_ALLOC +@defmac ORDER_REGS_FOR_LOCAL_ALLOC A C statement (sans semicolon) to choose the order in which to allocate hard registers for pseudo-registers local to a basic block. @@ -1980,7 +2007,7 @@ The macro body should not assume anything about the contents of @code{reg_alloc_order} before execution of the macro. On most machines, it is not necessary to define this macro. -@end table +@end defmac @node Values in Registers @subsection How Values Fit in Registers @@ -1989,9 +2016,7 @@ This section discusses the macros that describe which kinds of values (specifically, which machine modes) each register can hold, and how many consecutive registers are needed for a given mode. -@table @code -@findex HARD_REGNO_NREGS -@item HARD_REGNO_NREGS (@var{regno}, @var{mode}) +@defmac HARD_REGNO_NREGS (@var{regno}, @var{mode}) A C expression for the number of consecutive hard registers, starting at register number @var{regno}, required to hold a value of mode @var{mode}. @@ -2004,9 +2029,18 @@ definition of this macro is ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ / UNITS_PER_WORD) @end smallexample +@end defmac + +@defmac REGMODE_NATURAL_SIZE (@var{mode}) +Define this macro if the natural size of registers that hold values +of mode @var{mode} is not the word size. It is a C expression that +should give the natural size in bytes for the specified mode. It is +used by the register allocator to try to optimize its results. This +happens for example on SPARC 64-bit where the natural size of +floating-point registers is still 32-bit. +@end defmac -@findex HARD_REGNO_MODE_OK -@item HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) +@defmac HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) A C expression that is nonzero if it is permissible to store a value of mode @var{mode} in hard register number @var{regno} (or in several registers starting with that one). For a machine where all registers @@ -2065,9 +2099,9 @@ so that it is better to store a value in a stack frame than in such a register if floating point arithmetic is not being done. As long as the floating registers are not in class @code{GENERAL_REGS}, they will not be used unless some pattern's constraint asks for one. +@end defmac -@findex MODES_TIEABLE_P -@item MODES_TIEABLE_P (@var{mode1}, @var{mode2}) +@defmac MODES_TIEABLE_P (@var{mode1}, @var{mode2}) A C expression that is nonzero if a value of mode @var{mode1} is accessible in mode @var{mode2} without copying. @@ -2081,13 +2115,13 @@ accessibility of the value in a narrower mode. You should define this macro to return nonzero in as many cases as possible since doing so will allow GCC to perform better register allocation. +@end defmac -@findex AVOID_CCMODE_COPIES -@item AVOID_CCMODE_COPIES +@defmac AVOID_CCMODE_COPIES Define this macro if the compiler should avoid copies to/from @code{CCmode} registers. You should only define this macro if support for copying to/from @code{CCmode} is incomplete. -@end table +@end defmac @node Leaf Functions @subsection Handling Leaf Functions @@ -2112,9 +2146,7 @@ suitable for leaf function treatment. So it needs to renumber the registers in order to output a leaf function. The following macros accomplish this. -@table @code -@findex LEAF_REGISTERS -@item LEAF_REGISTERS +@defmac LEAF_REGISTERS Name of a char vector, indexed by hard register number, which contains 1 for a register that is allowable in a candidate for leaf function treatment. @@ -2127,9 +2159,9 @@ in this vector. Define this macro only if the target machine offers a way to optimize the treatment of leaf functions. +@end defmac -@findex LEAF_REG_REMAP -@item LEAF_REG_REMAP (@var{regno}) +@defmac LEAF_REG_REMAP (@var{regno}) A C expression whose value is the register number to which @var{regno} should be renumbered, when a function is treated as a leaf function. @@ -2140,7 +2172,7 @@ will cause the compiler to abort. Define this macro only if the target machine offers a way to optimize the treatment of leaf functions, and registers need to be renumbered to do this. -@end table +@end defmac @findex current_function_is_leaf @findex current_function_uses_only_leaf_regs @@ -2161,28 +2193,31 @@ only useful if @code{LEAF_REGISTERS} is defined. @subsection Registers That Form a Stack There are special features to handle computers where some of the -``registers'' form a stack, as in the 80387 coprocessor for the 80386. -Stack registers are normally written by pushing onto the stack, and are -numbered relative to the top of the stack. +``registers'' form a stack. Stack registers are normally written by +pushing onto the stack, and are numbered relative to the top of the +stack. Currently, GCC can only handle one group of stack-like registers, and -they must be consecutively numbered. - -@table @code -@findex STACK_REGS -@item STACK_REGS +they must be consecutively numbered. Furthermore, the existing +support for stack-like registers is specific to the 80387 floating +point coprocessor. If you have a new architecture that uses +stack-like registers, you will need to do substantial work on +@file{reg-stack.c} and write your machine description to cooperate +with it, as well as defining these macros. + +@defmac STACK_REGS Define this if the machine has any stack-like registers. +@end defmac -@findex FIRST_STACK_REG -@item FIRST_STACK_REG +@defmac FIRST_STACK_REG The number of the first stack-like register. This one is the top of the stack. +@end defmac -@findex LAST_STACK_REG -@item LAST_STACK_REG +@defmac LAST_STACK_REG The number of the last stack-like register. This one is the bottom of the stack. -@end table +@end defmac @node Register Classes @section Register Classes @@ -2247,34 +2282,32 @@ instruction must have a subclass consisting of registers from which single-byte values can be loaded or stored. This is so that @code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. -@table @code -@findex enum reg_class -@item enum reg_class -An enumeral type that must be defined with all the register class names -as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS} -must be the last register class, followed by one more enumeral value, +@deftp {Data type} {enum reg_class} +An enumerated type that must be defined with all the register class names +as enumerated values. @code{NO_REGS} must be first. @code{ALL_REGS} +must be the last register class, followed by one more enumerated value, @code{LIM_REG_CLASSES}, which is not a register class but rather tells how many classes there are. Each register class has a number, which is the value of casting the class name to type @code{int}. The number serves as an index in many of the tables described below. +@end deftp -@findex N_REG_CLASSES -@item N_REG_CLASSES +@defmac N_REG_CLASSES The number of distinct register classes, defined as follows: -@example +@smallexample #define N_REG_CLASSES (int) LIM_REG_CLASSES -@end example +@end smallexample +@end defmac -@findex REG_CLASS_NAMES -@item REG_CLASS_NAMES +@defmac REG_CLASS_NAMES An initializer containing the names of the register classes as C string constants. These names are used in writing some of the debugging dumps. +@end defmac -@findex REG_CLASS_CONTENTS -@item REG_CLASS_CONTENTS +@defmac REG_CLASS_CONTENTS An initializer containing the contents of the register classes, as integers which are bit masks. The @var{n}th integer specifies the contents of class @var{n}. The way the integer @var{mask} is interpreted is that @@ -2287,61 +2320,82 @@ for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. In this situation, the first integer in each sub-initializer corresponds to registers 0 through 31, the second integer to registers 32 through 63, and so on. +@end defmac -@findex REGNO_REG_CLASS -@item REGNO_REG_CLASS (@var{regno}) +@defmac REGNO_REG_CLASS (@var{regno}) A C expression whose value is a register class containing hard register @var{regno}. In general there is more than one such class; choose a class which is @dfn{minimal}, meaning that no smaller class also contains the register. +@end defmac -@findex BASE_REG_CLASS -@item BASE_REG_CLASS +@defmac BASE_REG_CLASS A macro whose definition is the name of the class to which a valid base register must belong. A base register is one used in an address which is the register value plus a displacement. +@end defmac -@findex MODE_BASE_REG_CLASS -@item MODE_BASE_REG_CLASS (@var{mode}) +@defmac MODE_BASE_REG_CLASS (@var{mode}) This is a variation of the @code{BASE_REG_CLASS} macro which allows the selection of a base register in a mode dependent manner. If @var{mode} is VOIDmode then it should return the same value as @code{BASE_REG_CLASS}. +@end defmac -@findex INDEX_REG_CLASS -@item INDEX_REG_CLASS +@defmac INDEX_REG_CLASS A macro whose definition is the name of the class to which a valid index register must belong. An index register is one used in an address where its value is either multiplied by a scale factor or added to another register (as well as added to a displacement). +@end defmac + +@defmac CONSTRAINT_LEN (@var{char}, @var{str}) +For the constraint at the start of @var{str}, which starts with the letter +@var{c}, return the length. This allows you to have register class / +constant / extra constraints that are longer than a single letter; +you don't need to define this macro if you can do with single-letter +constraints only. The definition of this macro should use +DEFAULT_CONSTRAINT_LEN for all the characters that you don't want +to handle specially. +There are some sanity checks in genoutput.c that check the constraint lengths +for the md file, so you can also use this macro to help you while you are +transitioning from a byzantine single-letter-constraint scheme: when you +return a negative length for a constraint you want to re-use, genoutput +will complain about every instance where it is used in the md file. +@end defmac -@findex REG_CLASS_FROM_LETTER -@item REG_CLASS_FROM_LETTER (@var{char}) +@defmac REG_CLASS_FROM_LETTER (@var{char}) A C expression which defines the machine-dependent operand constraint letters for register classes. If @var{char} is such a letter, the value should be the register class corresponding to it. Otherwise, the value should be @code{NO_REGS}. The register letter @samp{r}, corresponding to class @code{GENERAL_REGS}, will not be passed to this macro; you do not need to handle it. +@end defmac + +@defmac REG_CLASS_FROM_CONSTRAINT (@var{char}, @var{str}) +Like @code{REG_CLASS_FROM_LETTER}, but you also get the constraint string +passed in @var{str}, so that you can use suffixes to distinguish between +different variants. +@end defmac -@findex REGNO_OK_FOR_BASE_P -@item REGNO_OK_FOR_BASE_P (@var{num}) +@defmac REGNO_OK_FOR_BASE_P (@var{num}) A C expression which is nonzero if register number @var{num} is suitable for use as a base register in operand addresses. It may be either a suitable hard register or a pseudo register that has been allocated such a hard register. +@end defmac -@findex REGNO_MODE_OK_FOR_BASE_P -@item REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode}) +@defmac REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode}) A C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that that expression may examine the mode of the memory reference in @var{mode}. You should define this macro if the mode of the memory reference affects whether a register may be used as a base register. If you define this macro, the compiler will use it instead of @code{REGNO_OK_FOR_BASE_P}. +@end defmac -@findex REGNO_OK_FOR_INDEX_P -@item REGNO_OK_FOR_INDEX_P (@var{num}) +@defmac REGNO_OK_FOR_INDEX_P (@var{num}) A C expression which is nonzero if register number @var{num} is suitable for use as an index register in operand addresses. It may be either a suitable hard register or a pseudo register that has been @@ -2355,18 +2409,18 @@ labeling is used must fit the machine's constraints of which registers may serve in each capacity. The compiler will try both labelings, looking for one that is valid, and will reload one or both registers only if neither labeling works. +@end defmac -@findex PREFERRED_RELOAD_CLASS -@item PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) +@defmac PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) A C expression that places additional restrictions on the register class to use when it is necessary to copy value @var{x} into a register in class @var{class}. The value is a register class; perhaps @var{class}, or perhaps another, smaller class. On many machines, the following definition is safe: -@example +@smallexample #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS -@end example +@end smallexample Sometimes returning a more restrictive class makes better code. For example, on the 68000, when @var{x} is an integer constant that is in range @@ -2374,19 +2428,26 @@ for a @samp{moveq} instruction, the value of this macro is always @code{DATA_REGS} as long as @var{class} includes the data registers. Requiring a data register guarantees that a @samp{moveq} will be used. -If @var{x} is a @code{const_double}, by returning @code{NO_REGS} -you can force @var{x} into a memory constant. This is useful on -certain machines where immediate floating values cannot be loaded into -certain kinds of registers. +One case where @code{PREFERRED_RELOAD_CLASS} must not return +@var{class} is if @var{x} is a legitimate constant which cannot be +loaded into some register class. By returning @code{NO_REGS} you can +force @var{x} into a memory location. For example, rs6000 can load +immediate values into general-purpose registers, but does not have an +instruction for loading an immediate value into a floating-point +register, so @code{PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when +@var{x} is a floating-point constant. If the constant can't be loaded +into any kind of register, code generation will be better if +@code{LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead +of using @code{PREFERRED_RELOAD_CLASS}. +@end defmac -@findex PREFERRED_OUTPUT_RELOAD_CLASS -@item PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class}) +@defmac PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class}) Like @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of input reloads. If you don't define this macro, the default is to use @var{class}, unchanged. +@end defmac -@findex LIMIT_RELOAD_CLASS -@item LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) +@defmac LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) A C expression that places additional restrictions on the register class to use when it is necessary to be able to hold a value of mode @var{mode} in a reload register for which class @var{class} would @@ -2400,13 +2461,11 @@ smaller class. Don't define this macro unless the target machine has limitations which require the macro to do something nontrivial. +@end defmac -@findex SECONDARY_RELOAD_CLASS -@findex SECONDARY_INPUT_RELOAD_CLASS -@findex SECONDARY_OUTPUT_RELOAD_CLASS -@item SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) -@itemx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) -@itemx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) +@defmac SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) +@defmacx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) +@defmacx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) Many machines have some registers that cannot be copied directly to or from memory or even from other types of registers. An example is the @samp{MQ} register, which on most machines, can only be copied to or @@ -2465,9 +2524,9 @@ would not be helpful. Instead, a stack location must be used to perform the copy and the @code{mov@var{m}} pattern should use memory as an intermediate storage. This case often occurs between floating-point and general registers. +@end defmac -@findex SECONDARY_MEMORY_NEEDED -@item SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) +@defmac SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) Certain machines have the property that some registers cannot be copied to some other registers without using memory. Define this macro on those machines to be a C expression that is nonzero if objects of mode @@ -2476,9 +2535,9 @@ class @var{class2} by storing a register of @var{class1} into memory and loading that memory location into a register of @var{class2}. Do not define this macro if its value would always be zero. +@end defmac -@findex SECONDARY_MEMORY_NEEDED_RTX -@item SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) +@defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) Normally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler allocates a stack slot for a memory location needed for register copies. If this macro is defined, the compiler instead uses the memory location @@ -2486,9 +2545,9 @@ defined by this macro. Do not define this macro if you do not define @code{SECONDARY_MEMORY_NEEDED}. +@end defmac -@findex SECONDARY_MEMORY_NEEDED_MODE -@item SECONDARY_MEMORY_NEEDED_MODE (@var{mode}) +@defmac SECONDARY_MEMORY_NEEDED_MODE (@var{mode}) When the compiler needs a secondary memory location to copy between two registers of mode @var{mode}, it normally allocates sufficient memory to hold a quantity of @code{BITS_PER_WORD} bits and performs the store and @@ -2510,9 +2569,9 @@ details. Do not define this macro if you do not define @code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that is @code{BITS_PER_WORD} bits wide is correct for your machine. +@end defmac -@findex SMALL_REGISTER_CLASSES -@item SMALL_REGISTER_CLASSES +@defmac SMALL_REGISTER_CLASSES On some machines, it is risky to let hard registers live across arbitrary insns. Typically, these machines have instructions that require values to be in specific registers (like an accumulator), and reload will fail @@ -2529,9 +2588,9 @@ that can be performed in some cases. If you do not define this macro with a nonzero value when it is required, the compiler will run out of spill registers and print a fatal error message. For most machines, you should not define this macro at all. +@end defmac -@findex CLASS_LIKELY_SPILLED_P -@item CLASS_LIKELY_SPILLED_P (@var{class}) +@defmac CLASS_LIKELY_SPILLED_P (@var{class}) A C expression whose value is nonzero if pseudos that have been assigned to registers of class @var{class} would likely be spilled because registers of @var{class} are needed for spill registers. @@ -2547,9 +2606,9 @@ register. If there would not be another register available for reallocation, you should not change the definition of this macro since the only effect of such a definition would be to slow down register allocation. +@end defmac -@findex CLASS_MAX_NREGS -@item CLASS_MAX_NREGS (@var{class}, @var{mode}) +@defmac CLASS_MAX_NREGS (@var{class}, @var{mode}) A C expression for the maximum number of consecutive registers of class @var{class} needed to hold a value of mode @var{mode}. @@ -2560,8 +2619,9 @@ should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, This macro helps control the handling of multiple-word values in the reload pass. +@end defmac -@item CANNOT_CHANGE_MODE_CLASS(@var{from}, @var{to}, @var{class}) +@defmac CANNOT_CHANGE_MODE_CLASS (@var{from}, @var{to}, @var{class}) If defined, a C expression that returns nonzero for a @var{class} for which a change from mode @var{from} to mode @var{to} is invalid. @@ -2572,19 +2632,17 @@ does not store the low-order 32 bits, as would be the case for a normal register. Therefore, @file{alpha.h} defines @code{CANNOT_CHANGE_MODE_CLASS} as below: -@example +@smallexample #define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \ (GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \ ? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0) -@end example -@end table +@end smallexample +@end defmac Three other special macros describe which operands fit which constraint letters. -@table @code -@findex CONST_OK_FOR_LETTER_P -@item CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) +@defmac CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) A C expression that defines the machine-dependent operand constraint letters (@samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}) that specify particular ranges of integer values. If @var{c} is one of those @@ -2592,9 +2650,15 @@ letters, the expression should check that @var{value}, an integer, is in the appropriate range and return 1 if so, 0 otherwise. If @var{c} is not one of those letters, the value should be 0 regardless of @var{value}. +@end defmac + +@defmac CONST_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str}) +Like @code{CONST_OK_FOR_LETTER_P}, but you also get the constraint +string passed in @var{str}, so that you can use suffixes to distinguish +between different variants. +@end defmac -@findex CONST_DOUBLE_OK_FOR_LETTER_P -@item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) +@defmac CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) A C expression that defines the machine-dependent operand constraint letters that specify particular ranges of @code{const_double} values (@samp{G} or @samp{H}). @@ -2608,13 +2672,20 @@ letters, the value should be 0 regardless of @var{value}. @code{DImode} fixed-point constants. A given letter can accept either or both kinds of values. It can use @code{GET_MODE} to distinguish between these kinds. +@end defmac + +@defmac CONST_DOUBLE_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str}) +Like @code{CONST_DOUBLE_OK_FOR_LETTER_P}, but you also get the constraint +string passed in @var{str}, so that you can use suffixes to distinguish +between different variants. +@end defmac -@findex EXTRA_CONSTRAINT -@item EXTRA_CONSTRAINT (@var{value}, @var{c}) +@defmac EXTRA_CONSTRAINT (@var{value}, @var{c}) A C expression that defines the optional machine-dependent constraint letters that can be used to segregate specific types of operands, usually memory references, for the target machine. Any letter that is not -elsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} +elsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} / +@code{REG_CLASS_FROM_CONSTRAINT} may be used. Normally this macro will not be defined. If it is required for a particular target machine, it should return 1 @@ -2629,17 +2700,24 @@ letter @samp{Q} is defined as representing a memory address that does a @samp{Q} constraint on the input and @samp{r} on the output. The next alternative specifies @samp{m} on the input and a register class that does not include r0 on the output. +@end defmac + +@defmac EXTRA_CONSTRAINT_STR (@var{value}, @var{c}, @var{str}) +Like @code{EXTRA_CONSTRAINT}, but you also get the constraint string passed +in @var{str}, so that you can use suffixes to distinguish between different +variants. +@end defmac -@findex EXTRA_MEMORY_CONSTRAINT -@item EXTRA_MEMORY_CONSTRAINT (@var{c}) +@defmac EXTRA_MEMORY_CONSTRAINT (@var{c}, @var{str}) A C expression that defines the optional machine-dependent constraint letters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should be treated like memory constraints by the reload pass. -It should return 1 if the operand type represented by the constraint -letter @var{c} comprises a subset of all memory references including -all those whose address is simply a base register. This allows the reload -pass to reload an operand, if it does not directly correspond to the operand +It should return 1 if the operand type represented by the constraint +at the start of @var{str}, the first letter of which is the letter @var{c}, + comprises a subset of all memory references including +all those whose address is simply a base register. This allows the reload +pass to reload an operand, if it does not directly correspond to the operand type of @var{c}, by copying its address into a base register. For example, on the S/390, some instructions do not accept arbitrary @@ -2651,23 +2729,25 @@ a @samp{Q} constraint can handle any memory operand, because the reload pass knows it can be reloaded by copying the memory address into a base register if required. This is analogous to the way a @samp{o} constraint can handle any memory operand. +@end defmac -@findex EXTRA_ADDRESS_CONSTRAINT -@item EXTRA_ADDRESS_CONSTRAINT (@var{c}) +@defmac EXTRA_ADDRESS_CONSTRAINT (@var{c}, @var{str}) A C expression that defines the optional machine-dependent constraint -letters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should +letters, amongst those accepted by @code{EXTRA_CONSTRAINT} / +@code{EXTRA_CONSTRAINT_STR}, that should be treated like address constraints by the reload pass. -It should return 1 if the operand type represented by the constraint -letter @var{c} comprises a subset of all memory addresses including -all those that consist of just a base register. This allows the reload -pass to reload an operand, if it does not directly correspond to the operand -type of @var{c}, by copying it into a base register. +It should return 1 if the operand type represented by the constraint +at the start of @var{str}, which starts with the letter @var{c}, comprises +a subset of all memory addresses including +all those that consist of just a base register. This allows the reload +pass to reload an operand, if it does not directly correspond to the operand +type of @var{str}, by copying it into a base register. Any constraint marked as @code{EXTRA_ADDRESS_CONSTRAINT} can only -be used with the @code{address_operand} predicate. It is treated +be used with the @code{address_operand} predicate. It is treated analogously to the @samp{p} constraint. -@end table +@end defmac @node Stack and Calling @section Stack Layout and Calling Conventions @@ -2700,19 +2780,16 @@ This describes the stack layout and calling conventions. @c prevent bad page break with this line Here is the basic stack layout. -@table @code -@findex STACK_GROWS_DOWNWARD -@item STACK_GROWS_DOWNWARD +@defmac STACK_GROWS_DOWNWARD Define this macro if pushing a word onto the stack moves the stack pointer to a smaller address. When we say, ``define this macro if @dots{},'' it means that the compiler checks this macro only with @code{#ifdef} so the precise definition used does not matter. +@end defmac -@findex STACK_PUSH_CODE -@item STACK_PUSH_CODE - +@defmac STACK_PUSH_CODE This macro defines the operation used when something is pushed on the stack. In RTL, a push operation will be @code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})} @@ -2726,19 +2803,19 @@ space for the next item on the stack. The default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is defined, which is almost always right, and @code{PRE_INC} otherwise, which is often wrong. +@end defmac -@findex FRAME_GROWS_DOWNWARD -@item FRAME_GROWS_DOWNWARD +@defmac FRAME_GROWS_DOWNWARD Define this macro if the addresses of local variable slots are at negative offsets from the frame pointer. +@end defmac -@findex ARGS_GROW_DOWNWARD -@item ARGS_GROW_DOWNWARD +@defmac ARGS_GROW_DOWNWARD Define this macro if successive arguments to a function occupy decreasing addresses on the stack. +@end defmac -@findex STARTING_FRAME_OFFSET -@item STARTING_FRAME_OFFSET +@defmac STARTING_FRAME_OFFSET Offset from the frame pointer to the first local variable slot to be allocated. If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by @@ -2747,36 +2824,46 @@ Otherwise, it is found by adding the length of the first slot to the value @code{STARTING_FRAME_OFFSET}. @c i'm not sure if the above is still correct.. had to change it to get @c rid of an overfull. --mew 2feb93 +@end defmac + +@defmac STACK_ALIGNMENT_NEEDED +Define to zero to disable final alignment of the stack during reload. +The nonzero default for this macro is suitable for most ports. + +On ports where @code{STARTING_FRAME_OFFSET} is nonzero or where there +is a register save block following the local block that doesn't require +alignment to @code{STACK_BOUNDARY}, it may be beneficial to disable +stack alignment and do it in the backend. +@end defmac -@findex STACK_POINTER_OFFSET -@item STACK_POINTER_OFFSET +@defmac STACK_POINTER_OFFSET Offset from the stack pointer register to the first location at which outgoing arguments are placed. If not specified, the default value of zero is used. This is the proper value for most machines. If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above the first location at which outgoing arguments are placed. +@end defmac -@findex FIRST_PARM_OFFSET -@item FIRST_PARM_OFFSET (@var{fundecl}) +@defmac FIRST_PARM_OFFSET (@var{fundecl}) Offset from the argument pointer register to the first argument's address. On some machines it may depend on the data type of the function. If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above the first argument's address. +@end defmac -@findex STACK_DYNAMIC_OFFSET -@item STACK_DYNAMIC_OFFSET (@var{fundecl}) +@defmac STACK_DYNAMIC_OFFSET (@var{fundecl}) Offset from the stack pointer register to an item dynamically allocated on the stack, e.g., by @code{alloca}. The default value for this macro is @code{STACK_POINTER_OFFSET} plus the length of the outgoing arguments. The default is correct for most machines. See @file{function.c} for details. +@end defmac -@findex DYNAMIC_CHAIN_ADDRESS -@item DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) +@defmac DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) A C expression whose value is RTL representing the address in a stack frame where the pointer to the caller's frame is stored. Assume that @var{frameaddr} is an RTL expression for the address of the stack frame @@ -2785,25 +2872,25 @@ itself. If you don't define this macro, the default is to return the value of @var{frameaddr}---that is, the stack frame address is also the address of the stack word that points to the previous frame. +@end defmac -@findex SETUP_FRAME_ADDRESSES -@item SETUP_FRAME_ADDRESSES +@defmac SETUP_FRAME_ADDRESSES If defined, a C expression that produces the machine-specific code to setup the stack so that arbitrary frames can be accessed. For example, on the SPARC, we must flush all of the register windows to the stack before we can access arbitrary stack frames. You will seldom need to define this macro. +@end defmac -@findex BUILTIN_SETJMP_FRAME_VALUE -@item BUILTIN_SETJMP_FRAME_VALUE +@defmac BUILTIN_SETJMP_FRAME_VALUE If defined, a C expression that contains an rtx that is used to store the address of the current frame into the built in @code{setjmp} buffer. The default value, @code{virtual_stack_vars_rtx}, is correct for most machines. One reason you may need to define this macro is if @code{hard_frame_pointer_rtx} is the appropriate value on your machine. +@end defmac -@findex RETURN_ADDR_RTX -@item RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) +@defmac RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) A C expression whose value is RTL representing the value of the return address for the frame @var{count} steps up from the current frame, after the prologue. @var{frameaddr} is the frame pointer of the @var{count} @@ -2813,14 +2900,14 @@ frame, or the frame pointer of the @var{count} @minus{} 1 frame if The value of the expression must always be the correct address when @var{count} is zero, but may be @code{NULL_RTX} if there is not way to determine the return address of other frames. +@end defmac -@findex RETURN_ADDR_IN_PREVIOUS_FRAME -@item RETURN_ADDR_IN_PREVIOUS_FRAME +@defmac RETURN_ADDR_IN_PREVIOUS_FRAME Define this if the return address of a particular stack frame is accessed from the frame pointer of the previous stack frame. +@end defmac -@findex INCOMING_RETURN_ADDR_RTX -@item INCOMING_RETURN_ADDR_RTX +@defmac INCOMING_RETURN_ADDR_RTX A C expression whose value is RTL representing the location of the incoming return address at the beginning of any function, before the prologue. This RTL is either a @code{REG}, indicating that the return @@ -2832,9 +2919,17 @@ debugging information like that provided by DWARF 2. If this RTL is a @code{REG}, you should also define @code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}. +@end defmac -@findex INCOMING_FRAME_SP_OFFSET -@item INCOMING_FRAME_SP_OFFSET +@defmac DWARF_ALT_FRAME_RETURN_COLUMN +A C expression whose value is an integer giving a DWARF 2 column +number that may be used as an alternate return column. This should +be defined only if @code{DWARF_FRAME_RETURN_COLUMN} is set to a +general register, but an alternate column needs to be used for +signal frames. +@end defmac + +@defmac INCOMING_FRAME_SP_OFFSET A C expression whose value is an integer giving the offset, in bytes, from the value of the stack pointer register to the top of the stack frame at the beginning of any function, before the prologue. The top of @@ -2843,9 +2938,9 @@ previous frame, just before the call instruction. You only need to define this macro if you want to support call frame debugging information like that provided by DWARF 2. +@end defmac -@findex ARG_POINTER_CFA_OFFSET -@item ARG_POINTER_CFA_OFFSET (@var{fundecl}) +@defmac ARG_POINTER_CFA_OFFSET (@var{fundecl}) A C expression whose value is an integer giving the offset, in bytes, from the argument pointer to the canonical frame address (cfa). The final value should coincide with that calculated by @@ -2861,21 +2956,13 @@ and rs6000, and so such targets need to define this macro. You only need to define this macro if the default is incorrect, and you want to support call frame debugging information like that provided by DWARF 2. - -@findex SMALL_STACK -@item SMALL_STACK -Define this macro if the stack size for the target is very small. This -has the effect of disabling gcc's built-in @samp{alloca}, though -@samp{__builtin_alloca} is not affected. -@end table +@end defmac @node Exception Handling @subsection Exception Handling Support @cindex exception handling -@table @code -@findex EH_RETURN_DATA_REGNO -@item EH_RETURN_DATA_REGNO (@var{N}) +@defmac EH_RETURN_DATA_REGNO (@var{N}) A C expression whose value is the @var{N}th register number used for data by exception handlers, or @code{INVALID_REGNUM} if fewer than @var{N} registers are usable. @@ -2888,9 +2975,9 @@ but may negatively impact code size. The target must support at least You must define this macro if you want to support call frame exception handling like that provided by DWARF 2. +@end defmac -@findex EH_RETURN_STACKADJ_RTX -@item EH_RETURN_STACKADJ_RTX +@defmac EH_RETURN_STACKADJ_RTX A C expression whose value is RTL representing a location in which to store a stack adjustment to be applied before function return. This is used to unwind the stack to an exception handler's call frame. @@ -2900,14 +2987,14 @@ Typically this is a call-clobbered hard register that is otherwise untouched by the epilogue, but could also be a stack slot. Do not define this macro if the stack pointer is saved and restored -by the regular prolog and epilog code in the call frame itself; in -this case, the exception handling library routines will update the -stack location to be restored in place. Otherwise, you must define -this macro if you want to support call frame exception handling like +by the regular prolog and epilog code in the call frame itself; in +this case, the exception handling library routines will update the +stack location to be restored in place. Otherwise, you must define +this macro if you want to support call frame exception handling like that provided by DWARF 2. +@end defmac -@findex EH_RETURN_HANDLER_RTX -@item EH_RETURN_HANDLER_RTX +@defmac EH_RETURN_HANDLER_RTX A C expression whose value is RTL representing a location in which to store the address of an exception handler to which we should return. It will not be assigned on code paths that return normally. @@ -2916,8 +3003,8 @@ Typically this is the location in the call frame at which the normal return address is stored. For targets that return by popping an address off the stack, this might be a memory address just below the @emph{target} call frame rather than inside the current call -frame. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already -been assigned, so it may be used to calculate the location of the +frame. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already +been assigned, so it may be used to calculate the location of the target call frame. Some targets have more complex requirements than storing to an @@ -2926,9 +3013,16 @@ the @code{eh_return} instruction pattern should be used instead. If you want to support call frame exception handling, you must define either this macro or the @code{eh_return} instruction pattern. +@end defmac -@findex ASM_PREFERRED_EH_DATA_FORMAT -@item ASM_PREFERRED_EH_DATA_FORMAT(@var{code}, @var{global}) +@defmac RETURN_ADDR_OFFSET +If defined, an integer-valued C expression for which rtl will be generated +to add it to the exception handler address before it is searched in the +exception handling tables, and to subtract it again from the address before +using it to return to the exception handler. +@end defmac + +@defmac ASM_PREFERRED_EH_DATA_FORMAT (@var{code}, @var{global}) This macro chooses the encoding of pointers embedded in the exception handling sections. If at all possible, this should be defined such that the exception handling section will not require dynamic relocations, @@ -2941,9 +3035,9 @@ as found in @file{dwarf2.h}. If this macro is not defined, pointers will not be encoded but represented directly. +@end defmac -@findex ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX -@item ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX(@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done}) +@defmac ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX (@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done}) This macro allows the target to emit whatever special magic is required to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}. Generic code takes care of pc-relative and indirect encodings; this must @@ -2953,9 +3047,9 @@ This is a C statement that branches to @var{done} if the format was handled. @var{encoding} is the format chosen, @var{size} is the number of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF} to be emitted. +@end defmac -@findex MD_FALLBACK_FRAME_STATE_FOR -@item MD_FALLBACK_FRAME_STATE_FOR(@var{context}, @var{fs}, @var{success}) +@defmac MD_FALLBACK_FRAME_STATE_FOR (@var{context}, @var{fs}, @var{success}) This macro allows the target to add cpu and operating system specific code to the call-frame unwinder for use when there is no unwind data available. The most common reason to implement this macro is to unwind @@ -2969,7 +3063,23 @@ the stack pointer value. If the frame can be decoded, the register save addresses should be updated in @var{fs} and the macro should branch to @var{success}. If the frame cannot be decoded, the macro should do nothing. -@end table + +For proper signal handling in Java this macro is accompanied by +@code{MAKE_THROW_FRAME}, defined in @file{libjava/include/*-signal.h} headers. +@end defmac + +@defmac MD_HANDLE_UNWABI (@var{context}, @var{fs}) +This macro allows the target to add operating system specific code to the +call-frame unwinder to handle the IA-64 @code{.unwabi} unwinding directive, +usually used for signal or interrupt frames. + +This macro is called from @code{uw_update_context} in @file{unwind-ia64.c}. +@var{context} is an @code{_Unwind_Context}; +@var{fs} is an @code{_Unwind_FrameState}. Examine @code{fs->unwabi} +for the abi and context in the @code{.unwabi} directive. If the +@code{.unwabi} directive can be handled, the register save addresses should +be updated in @var{fs}. +@end defmac @node Stack Checking @subsection Specifying How Stack Checking is Done @@ -3000,59 +3110,57 @@ If neither of the above are true, GCC will generate code to periodically Normally, you will use the default values of these macros, so GCC will use the third approach. -@table @code -@findex STACK_CHECK_BUILTIN -@item STACK_CHECK_BUILTIN +@defmac STACK_CHECK_BUILTIN A nonzero value if stack checking is done by the configuration files in a machine-dependent manner. You should define this macro if stack checking is require by the ABI of your machine or if you would like to have to stack checking in some more efficient way than GCC's portable approach. The default value of this macro is zero. +@end defmac -@findex STACK_CHECK_PROBE_INTERVAL -@item STACK_CHECK_PROBE_INTERVAL +@defmac STACK_CHECK_PROBE_INTERVAL An integer representing the interval at which GCC must generate stack probe instructions. You will normally define this macro to be no larger than the size of the ``guard pages'' at the end of a stack area. The default value of 4096 is suitable for most systems. +@end defmac -@findex STACK_CHECK_PROBE_LOAD -@item STACK_CHECK_PROBE_LOAD +@defmac STACK_CHECK_PROBE_LOAD A integer which is nonzero if GCC should perform the stack probe as a load instruction and zero if GCC should use a store instruction. The default is zero, which is the most efficient choice on most systems. +@end defmac -@findex STACK_CHECK_PROTECT -@item STACK_CHECK_PROTECT +@defmac STACK_CHECK_PROTECT The number of bytes of stack needed to recover from a stack overflow, for languages where such a recovery is supported. The default value of 75 words should be adequate for most machines. +@end defmac -@findex STACK_CHECK_MAX_FRAME_SIZE -@item STACK_CHECK_MAX_FRAME_SIZE +@defmac STACK_CHECK_MAX_FRAME_SIZE The maximum size of a stack frame, in bytes. GCC will generate probe instructions in non-leaf functions to ensure at least this many bytes of stack are available. If a stack frame is larger than this size, stack checking will not be reliable and GCC will issue a warning. The default is chosen so that GCC only generates one instruction on most systems. You should normally not change the default value of this macro. +@end defmac -@findex STACK_CHECK_FIXED_FRAME_SIZE -@item STACK_CHECK_FIXED_FRAME_SIZE +@defmac STACK_CHECK_FIXED_FRAME_SIZE GCC uses this value to generate the above warning message. It represents the amount of fixed frame used by a function, not including space for any callee-saved registers, temporaries and user variables. You need only specify an upper bound for this amount and will normally use the default of four words. +@end defmac -@findex STACK_CHECK_MAX_VAR_SIZE -@item STACK_CHECK_MAX_VAR_SIZE +@defmac STACK_CHECK_MAX_VAR_SIZE The maximum size, in bytes, of an object that GCC will place in the fixed area of the stack frame when the user specifies @option{-fstack-check}. GCC computed the default from the values of the above macros and you will normally not need to override that default. -@end table +@end defmac @need 2000 @node Frame Registers @@ -3061,22 +3169,20 @@ normally not need to override that default. @c prevent bad page break with this line This discusses registers that address the stack frame. -@table @code -@findex STACK_POINTER_REGNUM -@item STACK_POINTER_REGNUM +@defmac STACK_POINTER_REGNUM The register number of the stack pointer register, which must also be a fixed register according to @code{FIXED_REGISTERS}. On most machines, the hardware determines which register this is. +@end defmac -@findex FRAME_POINTER_REGNUM -@item FRAME_POINTER_REGNUM +@defmac FRAME_POINTER_REGNUM The register number of the frame pointer register, which is used to access automatic variables in the stack frame. On some machines, the hardware determines which register this is. On other machines, you can choose any register you wish for this purpose. +@end defmac -@findex HARD_FRAME_POINTER_REGNUM -@item HARD_FRAME_POINTER_REGNUM +@defmac HARD_FRAME_POINTER_REGNUM On some machines the offset between the frame pointer and starting offset of the automatic variables is not known until after register allocation has been done (for example, because the saved registers are @@ -3096,9 +3202,9 @@ or @code{STACK_POINTER_REGNUM}. Do not define this macro if it would be the same as @code{FRAME_POINTER_REGNUM}. +@end defmac -@findex ARG_POINTER_REGNUM -@item ARG_POINTER_REGNUM +@defmac ARG_POINTER_REGNUM The register number of the arg pointer register, which is used to access the function's argument list. On some machines, this is the same as the frame pointer register. On some machines, the hardware determines which @@ -3107,9 +3213,9 @@ wish for this purpose. If this is not the same register as the frame pointer register, then you must mark it as a fixed register according to @code{FIXED_REGISTERS}, or arrange to be able to eliminate it (@pxref{Elimination}). +@end defmac -@findex RETURN_ADDRESS_POINTER_REGNUM -@item RETURN_ADDRESS_POINTER_REGNUM +@defmac RETURN_ADDRESS_POINTER_REGNUM The register number of the return address pointer register, which is used to access the current function's return address from the stack. On some machines, the return address is not at a fixed offset from the frame @@ -3119,11 +3225,10 @@ to point to the return address on the stack, and then be converted by Do not define this macro unless there is no other way to get the return address from the stack. +@end defmac -@findex STATIC_CHAIN_REGNUM -@findex STATIC_CHAIN_INCOMING_REGNUM -@item STATIC_CHAIN_REGNUM -@itemx STATIC_CHAIN_INCOMING_REGNUM +@defmac STATIC_CHAIN_REGNUM +@defmacx STATIC_CHAIN_INCOMING_REGNUM Register numbers used for passing a function's static chain pointer. If register windows are used, the register number as seen by the called function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register @@ -3135,11 +3240,10 @@ The static chain register need not be a fixed register. If the static chain is passed in memory, these macros should not be defined; instead, the next two macros should be defined. +@end defmac -@findex STATIC_CHAIN -@findex STATIC_CHAIN_INCOMING -@item STATIC_CHAIN -@itemx STATIC_CHAIN_INCOMING +@defmac STATIC_CHAIN +@defmacx STATIC_CHAIN_INCOMING If the static chain is passed in memory, these macros provide rtx giving @code{mem} expressions that denote where they are stored. @code{STATIC_CHAIN} and @code{STATIC_CHAIN_INCOMING} give the locations @@ -3156,9 +3260,9 @@ macros and should be used to refer to those items. If the static chain is passed in a register, the two previous macros should be defined instead. +@end defmac -@findex DWARF_FRAME_REGISTERS -@item DWARF_FRAME_REGISTERS +@defmac DWARF_FRAME_REGISTERS This macro specifies the maximum number of hard registers that can be saved in a call frame. This is used to size data structures used in DWARF2 exception handling. @@ -3173,17 +3277,46 @@ registers that are not call-saved. If this macro is not defined, it defaults to @code{FIRST_PSEUDO_REGISTER}. +@end defmac -@findex PRE_GCC3_DWARF_FRAME_REGISTERS -@item PRE_GCC3_DWARF_FRAME_REGISTERS +@defmac PRE_GCC3_DWARF_FRAME_REGISTERS This macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided for backward compatibility in pre GCC 3.0 compiled code. If this macro is not defined, it defaults to @code{DWARF_FRAME_REGISTERS}. +@end defmac -@end table +@defmac DWARF_REG_TO_UNWIND_COLUMN (@var{regno}) + +Define this macro if the target's representation for dwarf registers +is different than the internal representation for unwind column. +Given a dwarf register, this macro should return the internal unwind +column number to use instead. + +See the PowerPC's SPE target for an example. +@end defmac + +@defmac DWARF_FRAME_REGNUM (@var{regno}) + +Define this macro if the target's representation for dwarf registers +used in .eh_frame or .debug_frame is different from that used in other +debug info sections. Given a GCC hard register number, this macro +should return the .eh_frame register number. The default is +@code{DBX_REGISTER_NUMBER (@var{regno})}. + +@end defmac + +@defmac DWARF2_FRAME_REG_OUT (@var{regno}, @var{for_eh}) + +Define this macro to map register numbers held in the call frame info +that GCC has collected using @code{DWARF_FRAME_REGNUM} to those that +should be output in .debug_frame (@code{@var{for_eh}} is zero) and +.eh_frame (@code{@var{for_eh}} is nonzero). The default is to +return @code{@var{regno}}. + +@end defmac @node Elimination @subsection Eliminating Frame Pointer and Arg Pointer @@ -3191,9 +3324,7 @@ If this macro is not defined, it defaults to @c prevent bad page break with this line This is about eliminating the frame pointer and arg pointer. -@table @code -@findex FRAME_POINTER_REQUIRED -@item FRAME_POINTER_REQUIRED +@defmac FRAME_POINTER_REQUIRED A C expression which is nonzero if a function must have and use a frame pointer. This expression is evaluated in the reload pass. If its value is nonzero the function will have a frame pointer. @@ -3213,10 +3344,10 @@ them. In a function that does not require a frame pointer, the frame pointer register can be allocated for ordinary usage, unless you mark it as a fixed register. See @code{FIXED_REGISTERS} for more information. +@end defmac -@findex INITIAL_FRAME_POINTER_OFFSET @findex get_frame_size -@item INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) +@defmac INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) A C statement to store in the variable @var{depth-var} the difference between the frame pointer and the stack pointer values immediately after the function prologue. The value would be computed from information @@ -3227,9 +3358,9 @@ If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and need not be defined. Otherwise, it must be defined even if @code{FRAME_POINTER_REQUIRED} is defined to always be true; in that case, you may set @var{depth-var} to anything. +@end defmac -@findex ELIMINABLE_REGS -@item ELIMINABLE_REGS +@defmac ELIMINABLE_REGS If defined, this macro specifies a table of register pairs used to eliminate unneeded registers that point into the stack frame. If it is not defined, the only elimination attempted by the compiler is to replace @@ -3245,32 +3376,32 @@ replacing it with either the frame pointer or the argument pointer, depending on whether or not the frame pointer has been eliminated. In this case, you might specify: -@example +@smallexample #define ELIMINABLE_REGS \ @{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} -@end example +@end smallexample Note that the elimination of the argument pointer with the stack pointer is specified first since that is the preferred elimination. +@end defmac -@findex CAN_ELIMINATE -@item CAN_ELIMINATE (@var{from-reg}, @var{to-reg}) +@defmac CAN_ELIMINATE (@var{from-reg}, @var{to-reg}) A C expression that returns nonzero if the compiler is allowed to try to replace register number @var{from-reg} with register number @var{to-reg}. This macro need only be defined if @code{ELIMINABLE_REGS} is defined, and will usually be the constant 1, since most of the cases preventing register elimination are things that the compiler already knows about. +@end defmac -@findex INITIAL_ELIMINATION_OFFSET -@item INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) +@defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It specifies the initial difference between the specified pair of registers. This macro must be defined if @code{ELIMINABLE_REGS} is defined. -@end table +@end defmac @node Stack Arguments @subsection Passing Function Arguments on the Stack @@ -3281,48 +3412,52 @@ The macros in this section control how arguments are passed on the stack. See the following section for other macros that control passing certain arguments in registers. -@table @code -@findex PROMOTE_PROTOTYPES -@item PROMOTE_PROTOTYPES -A C expression whose value is nonzero if an argument declared in -a prototype as an integral type smaller than @code{int} should -actually be passed as an @code{int}. In addition to avoiding -errors in certain cases of mismatch, it also makes for better -code on certain machines. If the macro is not defined in target -header files, it defaults to 0. - -@findex PUSH_ARGS -@item PUSH_ARGS +@deftypefn {Target Hook} bool TARGET_PROMOTE_PROTOTYPES (tree @var{fntype}) +This target hook returns @code{true} if an argument declared in a +prototype as an integral type smaller than @code{int} should actually be +passed as an @code{int}. In addition to avoiding errors in certain +cases of mismatch, it also makes for better code on certain machines. +The default is to not promote prototypes. +@end deftypefn + +@defmac PUSH_ARGS A C expression. If nonzero, push insns will be used to pass outgoing arguments. If the target machine does not have a push instruction, set it to zero. That directs GCC to use an alternate strategy: to allocate the entire argument block and then store the arguments into it. When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too. +@end defmac -@findex PUSH_ROUNDING -@item PUSH_ROUNDING (@var{npushed}) +@defmac PUSH_ARGS_REVERSED +A C expression. If nonzero, function arguments will be evaluated from +last to first, rather than from first to last. If this macro is not +defined, it defaults to @code{PUSH_ARGS} on targets where the stack +and args grow in opposite directions, and 0 otherwise. +@end defmac + +@defmac PUSH_ROUNDING (@var{npushed}) A C expression that is the number of bytes actually pushed onto the stack when an instruction attempts to push @var{npushed} bytes. On some machines, the definition -@example +@smallexample #define PUSH_ROUNDING(BYTES) (BYTES) -@end example +@end smallexample @noindent will suffice. But on other machines, instructions that appear to push one byte actually push two bytes in an attempt to maintain alignment. Then the definition should be -@example +@smallexample #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) -@end example +@end smallexample +@end defmac -@findex ACCUMULATE_OUTGOING_ARGS @findex current_function_outgoing_args_size -@item ACCUMULATE_OUTGOING_ARGS +@defmac ACCUMULATE_OUTGOING_ARGS A C expression. If nonzero, the maximum amount of space required for outgoing arguments will be computed and placed into the variable @code{current_function_outgoing_args_size}. No space will be pushed @@ -3331,9 +3466,9 @@ increase the stack frame size by this amount. Setting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS} is not proper. +@end defmac -@findex REG_PARM_STACK_SPACE -@item REG_PARM_STACK_SPACE (@var{fndecl}) +@defmac REG_PARM_STACK_SPACE (@var{fndecl}) Define this macro if functions should assume that stack space has been allocated for arguments even when their values are passed in registers. @@ -3345,13 +3480,12 @@ which can be zero if GCC is calling a library function. This space can be allocated by the caller, or be a part of the machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says which. +@end defmac @c above is overfull. not sure what to do. --mew 5feb93 did @c something, not sure if it looks good. --mew 10feb93 -@findex MAYBE_REG_PARM_STACK_SPACE -@findex FINAL_REG_PARM_STACK_SPACE -@item MAYBE_REG_PARM_STACK_SPACE -@itemx FINAL_REG_PARM_STACK_SPACE (@var{const_size}, @var{var_size}) +@defmac MAYBE_REG_PARM_STACK_SPACE +@defmacx FINAL_REG_PARM_STACK_SPACE (@var{const_size}, @var{var_size}) Define these macros in addition to the one above if functions might allocate stack space for arguments even when their values are passed in registers. These should be used when the stack space allocated @@ -3375,18 +3509,18 @@ In each case this value can be easily computed. When deciding whether a called function needs such stack space, and how much space to reserve, GCC uses these two macros instead of @code{REG_PARM_STACK_SPACE}. +@end defmac -@findex OUTGOING_REG_PARM_STACK_SPACE -@item OUTGOING_REG_PARM_STACK_SPACE +@defmac OUTGOING_REG_PARM_STACK_SPACE Define this if it is the responsibility of the caller to allocate the area reserved for arguments passed in registers. If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls whether the space for these arguments counts in the value of @code{current_function_outgoing_args_size}. +@end defmac -@findex STACK_PARMS_IN_REG_PARM_AREA -@item STACK_PARMS_IN_REG_PARM_AREA +@defmac STACK_PARMS_IN_REG_PARM_AREA Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the stack parameters don't skip the area specified by it. @c i changed this, makes more sens and it should have taken care of the @@ -3396,9 +3530,9 @@ Normally, when a parameter is not passed in registers, it is placed on the stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro suppresses this behavior and causes the parameter to be passed on the stack in its natural location. +@end defmac -@findex RETURN_POPS_ARGS -@item RETURN_POPS_ARGS (@var{fundecl}, @var{funtype}, @var{stack-size}) +@defmac RETURN_POPS_ARGS (@var{fundecl}, @var{funtype}, @var{stack-size}) A C expression that should indicate the number of bytes of its own arguments that a function pops on returning, or 0 if the function pops no arguments and the caller must therefore pop them all @@ -3435,9 +3569,9 @@ arguments pop them but other functions (such as @code{printf}) pop nothing (the caller pops all). When this convention is in use, @var{funtype} is examined to determine whether a function takes a fixed number of arguments. +@end defmac -@findex CALL_POPS_ARGS -@item CALL_POPS_ARGS (@var{cum}) +@defmac CALL_POPS_ARGS (@var{cum}) A C expression that should indicate the number of bytes a call sequence pops off the stack. It is added to the value of @code{RETURN_POPS_ARGS} when compiling a function call. @@ -3450,8 +3584,7 @@ that pops certain registers off the stack, depending on the arguments that have been passed to the function. Since this is a property of the call site, not of the called function, @code{RETURN_POPS_ARGS} is not appropriate. - -@end table +@end defmac @node Register Arguments @subsection Passing Arguments in Registers @@ -3462,9 +3595,7 @@ This section describes the macros which let you control how various types of arguments are passed in registers or how they are arranged in the stack. -@table @code -@findex FUNCTION_ARG -@item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) +@defmac FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) A C expression that controls whether a function argument is passed in a register, and which register. @@ -3486,7 +3617,7 @@ pushed, zero suffices as a definition. The value of the expression can also be a @code{parallel} RTX@. This is used when an argument is passed in multiple locations. The mode of the -of the @code{parallel} should be the mode of the entire argument. The +@code{parallel} should be the mode of the entire argument. The @code{parallel} holds any number of @code{expr_list} pairs; each one describes where part of the argument is passed. In each @code{expr_list} the first operand must be a @code{reg} RTX for the hard @@ -3517,16 +3648,16 @@ is not defined and @code{FUNCTION_ARG} returns nonzero for such an argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is defined, the argument will be computed in the stack and then loaded into a register. +@end defmac -@findex MUST_PASS_IN_STACK -@item MUST_PASS_IN_STACK (@var{mode}, @var{type}) +@defmac MUST_PASS_IN_STACK (@var{mode}, @var{type}) Define as a C expression that evaluates to nonzero if we do not know how to pass TYPE solely in registers. The file @file{expr.h} defines a definition that is usually appropriate, refer to @file{expr.h} for additional documentation. +@end defmac -@findex FUNCTION_INCOMING_ARG -@item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) +@defmac FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) Define this macro if the target machine has ``register windows'', so that the register in which a function sees an arguments is not necessarily the same as the one in which the caller passed the @@ -3539,9 +3670,9 @@ where the arguments will arrive. If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG} serves both purposes. +@end defmac -@findex FUNCTION_ARG_PARTIAL_NREGS -@item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named}) +@defmac FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named}) A C expression for the number of words, at the beginning of an argument, that must be put in registers. The value must be zero for arguments that are passed entirely in registers or that are entirely @@ -3559,9 +3690,9 @@ registers. @code{FUNCTION_ARG} for these arguments should return the first register to be used by the caller for this argument; likewise @code{FUNCTION_INCOMING_ARG}, for the called function. +@end defmac -@findex FUNCTION_ARG_PASS_BY_REFERENCE -@item FUNCTION_ARG_PASS_BY_REFERENCE (@var{cum}, @var{mode}, @var{type}, @var{named}) +@defmac FUNCTION_ARG_PASS_BY_REFERENCE (@var{cum}, @var{mode}, @var{type}, @var{named}) A C expression that indicates when an argument must be passed by reference. If nonzero for an argument, a copy of that argument is made in memory and a pointer to the argument is passed instead of the argument itself. @@ -3576,9 +3707,9 @@ definition of this macro might be MUST_PASS_IN_STACK (MODE, TYPE) @end smallexample @c this is *still* too long. --mew 5feb93 +@end defmac -@findex FUNCTION_ARG_CALLEE_COPIES -@item FUNCTION_ARG_CALLEE_COPIES (@var{cum}, @var{mode}, @var{type}, @var{named}) +@defmac FUNCTION_ARG_CALLEE_COPIES (@var{cum}, @var{mode}, @var{type}, @var{named}) If defined, a C expression that indicates when it is the called function's responsibility to make a copy of arguments passed by invisible reference. Normally, the caller makes a copy and passes the address of the copy to the @@ -3587,9 +3718,9 @@ nonzero, the caller does not make a copy. Instead, it passes a pointer to the ``live'' value. The called function must not modify this value. If it can be determined that the value won't be modified, it need not make a copy; otherwise a copy must be made. +@end defmac -@findex CUMULATIVE_ARGS -@item CUMULATIVE_ARGS +@defmac CUMULATIVE_ARGS A C type for declaring a variable that is used as the first argument of @code{FUNCTION_ARG} and other related values. For some target machines, the type @code{int} suffices and can hold the number of bytes of @@ -3601,19 +3732,21 @@ variables to keep track of that. For target machines on which all arguments are passed on the stack, there is no need to store anything in @code{CUMULATIVE_ARGS}; however, the data structure must exist and should not be empty, so use @code{int}. +@end defmac -@findex INIT_CUMULATIVE_ARGS -@item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{indirect}) -A C statement (sans semicolon) for initializing the variable @var{cum} -for the state at the beginning of the argument list. The variable has -type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node -for the data type of the function which will receive the args, or 0 -if the args are to a compiler support library function. The value of -@var{indirect} is nonzero when processing an indirect call, for example -a call through a function pointer. The value of @var{indirect} is zero -for a call to an explicitly named function, a library function call, or when +@defmac INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{fndecl}, @var{n_named_args}) +A C statement (sans semicolon) for initializing the variable +@var{cum} for the state at the beginning of the argument list. The +variable has type @code{CUMULATIVE_ARGS}. The value of @var{fntype} +is the tree node for the data type of the function which will receive +the args, or 0 if the args are to a compiler support library function. +For direct calls that are not libcalls, @var{fndecl} contain the +declaration node of the function. @var{fndecl} is also set when @code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function -being compiled. +being compiled. @var{n_named_args} is set to the number of named +arguments, including a structure return address if it is passed as a +parameter, when making a call. When processing incoming arguments, +@var{n_named_args} is set to -1. When processing a call to a compiler support library function, @var{libname} identifies which one. It is a @code{symbol_ref} rtx which @@ -3621,17 +3754,17 @@ contains the name of the function, as a string. @var{libname} is 0 when an ordinary C function call is being processed. Thus, each time this macro is called, either @var{libname} or @var{fntype} is nonzero, but never both of them at once. +@end defmac -@findex INIT_CUMULATIVE_LIBCALL_ARGS -@item INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname}) +@defmac INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname}) Like @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls, it gets a @code{MODE} argument instead of @var{fntype}, that would be @code{NULL}. @var{indirect} would always be zero, too. If this macro is not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 0)} is used instead. +@end defmac -@findex INIT_CUMULATIVE_INCOMING_ARGS -@item INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) +@defmac INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of finding the arguments for the function being compiled. If this macro is undefined, @code{INIT_CUMULATIVE_ARGS} is used instead. @@ -3642,9 +3775,9 @@ argument @var{libname} exists for symmetry with @code{INIT_CUMULATIVE_ARGS}. @c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. @c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 +@end defmac -@findex FUNCTION_ARG_ADVANCE -@item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) +@defmac FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) A C statement (sans semicolon) to update the summarizer variable @var{cum} to advance past an argument in the argument list. The values @var{mode}, @var{type} and @var{named} describe that argument. @@ -3654,9 +3787,9 @@ the @emph{following} argument with @code{FUNCTION_ARG}, etc. This macro need not do anything if the argument in question was passed on the stack. The compiler knows how to track the amount of stack space used for arguments without any special help. +@end defmac -@findex FUNCTION_ARG_PADDING -@item FUNCTION_ARG_PADDING (@var{mode}, @var{type}) +@defmac FUNCTION_ARG_PADDING (@var{mode}, @var{type}) If defined, a C expression which determines whether, and in which direction, to pad out an argument with extra space. The value should be of type @code{enum direction}: either @code{upward} to pad above the argument, @@ -3670,38 +3803,54 @@ This macro has a default definition which is right for most systems. For little-endian machines, the default is to pad upward. For big-endian machines, the default is to pad downward for an argument of constant size shorter than an @code{int}, and upward otherwise. +@end defmac -@findex PAD_VARARGS_DOWN -@item PAD_VARARGS_DOWN +@defmac PAD_VARARGS_DOWN If defined, a C expression which determines whether the default implementation of va_arg will attempt to pad down before reading the next argument, if that argument is smaller than its aligned space as controlled by @code{PARM_BOUNDARY}. If this macro is not defined, all such arguments are padded down if @code{BYTES_BIG_ENDIAN} is true. +@end defmac -@findex FUNCTION_ARG_BOUNDARY -@item FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type}) +@defmac BLOCK_REG_PADDING (@var{mode}, @var{type}, @var{first}) +Specify padding for the last element of a block move between registers and +memory. @var{first} is nonzero if this is the only element. Defining this +macro allows better control of register function parameters on big-endian +machines, without using @code{PARALLEL} rtl. In particular, +@code{MUST_PASS_IN_STACK} need not test padding and mode of types in +registers, as there is no longer a "wrong" part of a register; For example, +a three byte aggregate may be passed in the high part of a register if so +required. +@end defmac + +@defmac FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type}) If defined, a C expression that gives the alignment boundary, in bits, of an argument with the specified mode and type. If it is not defined, @code{PARM_BOUNDARY} is used for all arguments. +@end defmac -@findex FUNCTION_ARG_REGNO_P -@item FUNCTION_ARG_REGNO_P (@var{regno}) +@defmac FUNCTION_ARG_REGNO_P (@var{regno}) A C expression that is nonzero if @var{regno} is the number of a hard register in which function arguments are sometimes passed. This does @emph{not} include implicit arguments such as the static chain and the structure-value address. On many machines, no registers can be used for this purpose since all function arguments are pushed on the stack. +@end defmac -@findex LOAD_ARGS_REVERSED -@item LOAD_ARGS_REVERSED -If defined, the order in which arguments are loaded into their -respective argument registers is reversed so that the last -argument is loaded first. This macro only affects arguments -passed in registers. - -@end table +@deftypefn {Target Hook} bool TARGET_SPLIT_COMPLEX_ARG (tree @var{type}) +This hook should return true if parameter of type @var{type} are passed +as two scalar parameters. By default, GCC will attempt to pack complex +arguments into the target's word size. Some ABIs require complex arguments +to be split and treated as their individual components. For example, on +AIX64, complex floats should be passed in a pair of floating point +registers, even though a complex float would fit in one 64-bit floating +point register. + +The default value of this hook is @code{NULL}, which is treated as always +false. +@end deftypefn @node Scalar Return @subsection How Scalar Function Values Are Returned @@ -3712,9 +3861,7 @@ passed in registers. This section discusses the macros that control returning scalars as values---values that can fit in registers. -@table @code -@findex FUNCTION_VALUE -@item FUNCTION_VALUE (@var{valtype}, @var{func}) +@defmac FUNCTION_VALUE (@var{valtype}, @var{func}) A C expression to create an RTX representing the place where a function returns a value of data type @var{valtype}. @var{valtype} is a tree node representing a data type. Write @code{TYPE_MODE @@ -3728,7 +3875,7 @@ register where the return value is stored. The value can also be a @code{parallel} RTX, if the return value is in multiple places. See @code{FUNCTION_ARG} for an explanation of the @code{parallel} form. -If @code{PROMOTE_FUNCTION_RETURN} is defined, you must apply the same +If @code{TARGET_PROMOTE_FUNCTION_RETURN} returns true, you must apply the same promotion rules specified in @code{PROMOTE_MODE} if @var{valtype} is a scalar type. @@ -3740,10 +3887,10 @@ known. @code{FUNCTION_VALUE} is not used for return vales with aggregate data types, because these are returned in another way. See -@code{STRUCT_VALUE_REGNUM} and related macros, below. +@code{TARGET_STRUCT_VALUE_RTX} and related macros, below. +@end defmac -@findex FUNCTION_OUTGOING_VALUE -@item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) +@defmac FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) Define this macro if the target machine has ``register windows'' so that the register in which a function returns its value is not the same as the one in which the caller sees the value. @@ -3758,10 +3905,10 @@ If @code{FUNCTION_OUTGOING_VALUE} is not defined, @code{FUNCTION_OUTGOING_VALUE} is not used for return vales with aggregate data types, because these are returned in another way. See -@code{STRUCT_VALUE_REGNUM} and related macros, below. +@code{TARGET_STRUCT_VALUE_RTX} and related macros, below. +@end defmac -@findex LIBCALL_VALUE -@item LIBCALL_VALUE (@var{mode}) +@defmac LIBCALL_VALUE (@var{mode}) A C expression to create an RTX representing the place where a library function returns a value of mode @var{mode}. If the precise function being called is known, @var{func} is a tree node @@ -3777,9 +3924,9 @@ compiled. The definition of @code{LIBRARY_VALUE} need not be concerned aggregate data types, because none of the library functions returns such types. +@end defmac -@findex FUNCTION_VALUE_REGNO_P -@item FUNCTION_VALUE_REGNO_P (@var{regno}) +@defmac FUNCTION_VALUE_REGNO_P (@var{regno}) A C expression that is nonzero if @var{regno} is the number of a hard register in which the values of called function may come back. @@ -3788,20 +3935,32 @@ second of a pair (for a value of type @code{double}, say) need not be recognized by this macro. So for most machines, this definition suffices: -@example +@smallexample #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) -@end example +@end smallexample If the machine has register windows, so that the caller and the called function use different registers for the return value, this macro should recognize only the caller's register numbers. +@end defmac -@findex APPLY_RESULT_SIZE -@item APPLY_RESULT_SIZE +@defmac APPLY_RESULT_SIZE Define this macro if @samp{untyped_call} and @samp{untyped_return} need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for saving and restoring an arbitrary return value. -@end table +@end defmac + +@deftypefn {Target Hook} bool TARGET_RETURN_IN_MSB (tree @var{type}) +This hook should return true if values of type @var{type} are returned +at the most significant end of a register (in other words, if they are +padded at the least significant end). You can assume that @var{type} +is returned in a register; the caller is required to check this. + +Note that the register provided by @code{FUNCTION_VALUE} must be able +to hold the complete return value. For example, if a 1-, 2- or 3-byte +structure is returned at the most significant end of a 4-byte register, +@code{FUNCTION_VALUE} should provide an @code{SImode} rtx. +@end deftypefn @node Aggregate Return @subsection How Large Values Are Returned @@ -3819,69 +3978,55 @@ is called the @dfn{structure value address}. This section describes how to control returning structure values in memory. -@table @code -@findex RETURN_IN_MEMORY -@item RETURN_IN_MEMORY (@var{type}) -A C expression which can inhibit the returning of certain function -values in registers, based on the type of value. A nonzero value says -to return the function value in memory, just as large structures are -always returned. Here @var{type} will be a C expression of type -@code{tree}, representing the data type of the value. +@deftypefn {Target Hook} bool TARGET_RETURN_IN_MEMORY (tree @var{type}, tree @var{fntype}) +This target hook should return a nonzero value to say to return the +function value in memory, just as large structures are always returned. +Here @var{type} will be the data type of the value, and @var{fntype} +will be the type of the function doing the returning, or @code{NULL} for +libcalls. Note that values of mode @code{BLKmode} must be explicitly handled -by this macro. Also, the option @option{-fpcc-struct-return} +by this function. Also, the option @option{-fpcc-struct-return} takes effect regardless of this macro. On most systems, it is -possible to leave the macro undefined; this causes a default +possible to leave the hook undefined; this causes a default definition to be used, whose value is the constant 1 for @code{BLKmode} values, and 0 otherwise. -Do not use this macro to indicate that structures and unions should always +Do not use this hook to indicate that structures and unions should always be returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} to indicate this. +@end deftypefn -@findex DEFAULT_PCC_STRUCT_RETURN -@item DEFAULT_PCC_STRUCT_RETURN +@defmac DEFAULT_PCC_STRUCT_RETURN Define this macro to be 1 if all structure and union return values must be in memory. Since this results in slower code, this should be defined only if needed for compatibility with other compilers or with an ABI@. If you define this macro to be 0, then the conventions used for structure -and union return values are decided by the @code{RETURN_IN_MEMORY} macro. +and union return values are decided by the @code{TARGET_RETURN_IN_MEMORY} +target hook. If not defined, this defaults to the value 1. +@end defmac -@findex STRUCT_VALUE_REGNUM -@item STRUCT_VALUE_REGNUM -If the structure value address is passed in a register, then -@code{STRUCT_VALUE_REGNUM} should be the number of that register. - -@findex STRUCT_VALUE -@item STRUCT_VALUE -If the structure value address is not passed in a register, define -@code{STRUCT_VALUE} as an expression returning an RTX for the place -where the address is passed. If it returns 0, the address is passed as -an ``invisible'' first argument. +@deftypefn {Target Hook} rtx TARGET_STRUCT_VALUE_RTX (tree @var{fndecl}, int @var{incoming}) +This target hook should return the location of the structure value +address (normally a @code{mem} or @code{reg}), or 0 if the address is +passed as an ``invisible'' first argument. Note that @var{fndecl} may +be @code{NULL}, for libcalls. -@findex STRUCT_VALUE_INCOMING_REGNUM -@item STRUCT_VALUE_INCOMING_REGNUM On some architectures the place where the structure value address is found by the called function is not the same place that the caller put it. This can be due to register windows, or it could be because the function prologue moves it to a different place. +@var{incoming} is @code{true} when the location is needed in +the context of the called function, and @code{false} in the context of +the caller. -If the incoming location of the structure value address is in a -register, define this macro as the register number. - -@findex STRUCT_VALUE_INCOMING -@item STRUCT_VALUE_INCOMING -If the incoming location is not a register, then you should define -@code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the -called function should find the value. If it should find the value on -the stack, define this to create a @code{mem} which refers to the frame -pointer. A definition of 0 means that the address is passed as an -``invisible'' first argument. +If @var{incoming} is @code{true} and the address is to be found on the +stack, return a @code{mem} which refers to the frame pointer. +@end deftypefn -@findex PCC_STATIC_STRUCT_RETURN -@item PCC_STATIC_STRUCT_RETURN +@defmac PCC_STATIC_STRUCT_RETURN Define this macro if the usual system convention on the target machine for returning structures and unions is for the called function to return the address of a static variable containing the value. @@ -3891,7 +4036,7 @@ pass an address to the subroutine. This macro has effect in @option{-fpcc-struct-return} mode, but it does nothing when you use @option{-freg-struct-return} mode. -@end table +@end defmac @node Caller Saves @subsection Caller-Saves Register Allocation @@ -3900,17 +4045,7 @@ If you enable it, GCC can save registers around function calls. This makes it possible to use call-clobbered registers to hold variables that must live across calls. -@table @code -@findex DEFAULT_CALLER_SAVES -@item DEFAULT_CALLER_SAVES -Define this macro if function calls on the target machine do not preserve -any registers; in other words, if @code{CALL_USED_REGISTERS} has 1 -for all registers. When defined, this macro enables @option{-fcaller-saves} -by default for all optimization levels. It has no effect for optimization -levels 2 and higher, where @option{-fcaller-saves} is the default. - -@findex CALLER_SAVE_PROFITABLE -@item CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) +@defmac CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) A C expression to determine whether it is worthwhile to consider placing a pseudo-register in a call-clobbered hard register and saving and restoring it around each function call. The expression should be 1 when @@ -3918,15 +4053,15 @@ this is worth doing, and 0 otherwise. If you don't define this macro, a default is used which is good on most machines: @code{4 * @var{calls} < @var{refs}}. +@end defmac -@findex HARD_REGNO_CALLER_SAVE_MODE -@item HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs}) +@defmac HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs}) A C expression specifying which mode is required for saving @var{nregs} of a pseudo-register in call-clobbered hard register @var{regno}. If @var{regno} is unsuitable for caller save, @code{VOIDmode} should be returned. For most machines this macro need not be defined since GCC will select the smallest suitable mode. -@end table +@end defmac @node Function Entry @subsection Function Entry and Exit @@ -4044,8 +4179,6 @@ arguments that a function should pop. @xref{Scalar Return}. @c tell? --mew 5feb93 @end deftypefn -@table @code - @itemize @bullet @item @findex current_function_pretend_args_size @@ -4086,39 +4219,39 @@ Normally, it is necessary for the macros The C variable @code{current_function_is_leaf} is nonzero for such a function. -@findex EXIT_IGNORE_STACK -@item EXIT_IGNORE_STACK +@defmac EXIT_IGNORE_STACK Define this macro as a C expression that is nonzero if the return instruction or the function epilogue ignores the value of the stack pointer; in other words, if it is safe to delete an instruction to -adjust the stack pointer before a return from the function. +adjust the stack pointer before a return from the function. The +default is 0. Note that this macro's value is relevant only for functions for which frame pointers are maintained. It is never safe to delete a final stack adjustment in a function that has no frame pointer, and the compiler knows this regardless of @code{EXIT_IGNORE_STACK}. +@end defmac -@findex EPILOGUE_USES -@item EPILOGUE_USES (@var{regno}) +@defmac EPILOGUE_USES (@var{regno}) Define this macro as a C expression that is nonzero for registers that are used by the epilogue or the @samp{return} pattern. The stack and frame pointer registers are already be assumed to be used as needed. +@end defmac -@findex EH_USES -@item EH_USES (@var{regno}) +@defmac EH_USES (@var{regno}) Define this macro as a C expression that is nonzero for registers that are used by the exception handling mechanism, and so should be considered live on entry to an exception edge. +@end defmac -@findex DELAY_SLOTS_FOR_EPILOGUE -@item DELAY_SLOTS_FOR_EPILOGUE +@defmac DELAY_SLOTS_FOR_EPILOGUE Define this macro if the function epilogue contains delay slots to which instructions from the rest of the function can be ``moved''. The definition should be a C expression whose value is an integer representing the number of delay slots there. +@end defmac -@findex ELIGIBLE_FOR_EPILOGUE_DELAY -@item ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) +@defmac ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) A C expression that returns 1 if @var{insn} can be placed in delay slot number @var{n} of the epilogue. @@ -4143,10 +4276,8 @@ outputting the insns in this list, usually by calling You need not define this macro if you did not define @code{DELAY_SLOTS_FOR_EPILOGUE}. +@end defmac -@end table - -@findex TARGET_ASM_OUTPUT_MI_THUNK @deftypefn {Target Hook} void TARGET_ASM_OUTPUT_MI_THUNK (FILE *@var{file}, tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, tree @var{function}) A function that outputs the assembler code for a thunk function, used to implement C++ virtual function calls with multiple @@ -4181,21 +4312,19 @@ front end will generate a less efficient heavyweight thunk that calls not support varargs. @end deftypefn -@findex TARGET_ASM_OUTPUT_MI_VCALL_THUNK @deftypefn {Target Hook} void TARGET_ASM_OUTPUT_MI_VCALL_THUNK (FILE *@var{file}, tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, int @var{vcall_offset}, tree @var{function}) A function like @code{TARGET_ASM_OUTPUT_MI_THUNK}, except that if @var{vcall_offset} is nonzero, an additional adjustment should be made after adding @code{delta}. In particular, if @var{p} is the adjusted pointer, the following adjustment should be made: -@example +@smallexample p += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)] -@end example +@end smallexample @noindent If this function is defined, it will always be used in place of @code{TARGET_ASM_OUTPUT_MI_THUNK}. - @end deftypefn @node Profiling @@ -4204,9 +4333,7 @@ If this function is defined, it will always be used in place of These macros will help you generate code for profiling. -@table @code -@findex FUNCTION_PROFILER -@item FUNCTION_PROFILER (@var{file}, @var{labelno}) +@defmac FUNCTION_PROFILER (@var{file}, @var{labelno}) A C statement or compound statement to output to @var{file} some assembler code to call the profiling subroutine @code{mcount}. @@ -4220,42 +4347,42 @@ Older implementations of @code{mcount} expect the address of a counter variable to be loaded into some register. The name of this variable is @samp{LP} followed by the number @var{labelno}, so you would generate the name using @samp{LP%d} in a @code{fprintf}. +@end defmac -@findex PROFILE_HOOK -@item PROFILE_HOOK +@defmac PROFILE_HOOK A C statement or compound statement to output to @var{file} some assembly code to call the profiling subroutine @code{mcount} even the target does not support profiling. +@end defmac -@findex NO_PROFILE_COUNTERS -@item NO_PROFILE_COUNTERS +@defmac NO_PROFILE_COUNTERS Define this macro if the @code{mcount} subroutine on your system does not need a counter variable allocated for each function. This is true for almost all modern implementations. If you define this macro, you must not use the @var{labelno} argument to @code{FUNCTION_PROFILER}. +@end defmac -@findex PROFILE_BEFORE_PROLOGUE -@item PROFILE_BEFORE_PROLOGUE +@defmac PROFILE_BEFORE_PROLOGUE Define this macro if the code for function profiling should come before the function prologue. Normally, the profiling code comes after. -@end table +@end defmac @node Tail Calls @subsection Permitting tail calls @cindex tail calls -@table @code -@findex FUNCTION_OK_FOR_SIBCALL -@item FUNCTION_OK_FOR_SIBCALL (@var{decl}) -A C expression that evaluates to true if it is ok to perform a sibling -call to @var{decl} from the current function. +@deftypefn {Target Hook} bool TARGET_FUNCTION_OK_FOR_SIBCALL (tree @var{decl}, tree @var{exp}) +True if it is ok to do sibling call optimization for the specified +call expression @var{exp}. @var{decl} will be the called function, +or @code{NULL} if this is an indirect call. It is not uncommon for limitations of calling conventions to prevent tail calls to functions outside the current unit of translation, or -during PIC compilation. Use this macro to enforce these restrictions, +during PIC compilation. The hook is used to enforce these restrictions, as the @code{sibcall} md pattern can not fail, or fall over to a -``normal'' call. -@end table +``normal'' call. The criteria for successful sibling call optimization +may vary greatly between different architectures. +@end deftypefn @node Varargs @section Implementing the Varargs Macros @@ -4278,9 +4405,7 @@ However, @code{va_start} should not use this argument. The way to find the end of the named arguments is with the built-in functions described below. -@table @code -@findex __builtin_saveregs -@item __builtin_saveregs () +@defmac __builtin_saveregs () Use this built-in function to save the argument registers in memory so that the varargs mechanism can access them. Both ISO and traditional versions of @code{va_start} must use @code{__builtin_saveregs}, unless @@ -4298,9 +4423,9 @@ This is because the registers must be saved before the function starts to use them for its own purposes. @c i rewrote the first sentence above to fix an overfull hbox. --mew @c 10feb93 +@end defmac -@findex __builtin_args_info -@item __builtin_args_info (@var{category}) +@defmac __builtin_args_info (@var{category}) Use this built-in function to find the first anonymous arguments in registers. @@ -4322,9 +4447,9 @@ of @code{va_start}, accessing each category just once and storing the value in the @code{va_list} object. This is because @code{va_list} will have to update the values, and there is no way to alter the values accessed by @code{__builtin_args_info}. +@end defmac -@findex __builtin_next_arg -@item __builtin_next_arg (@var{lastarg}) +@defmac __builtin_next_arg (@var{lastarg}) This is the equivalent of @code{__builtin_args_info}, for stack arguments. It returns the address of the first anonymous stack argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it @@ -4333,9 +4458,9 @@ argument. Use it in @code{va_start} to initialize the pointer for fetching arguments from the stack. Also use it in @code{va_start} to verify that the second parameter @var{lastarg} is the last named argument of the current function. +@end defmac -@findex __builtin_classify_type -@item __builtin_classify_type (@var{object}) +@defmac __builtin_classify_type (@var{object}) Since each machine has its own conventions for which data types are passed in which kind of register, your implementation of @code{va_arg} has to embody these conventions. The easiest way to categorize the @@ -4348,76 +4473,75 @@ kind of type that is---integer, floating, pointer, structure, and so on. The file @file{typeclass.h} defines an enumeration that you can use to interpret the values of @code{__builtin_classify_type}. -@end table +@end defmac These machine description macros help implement varargs: -@table @code -@findex EXPAND_BUILTIN_SAVEREGS -@item EXPAND_BUILTIN_SAVEREGS () -If defined, is a C expression that produces the machine-specific code -for a call to @code{__builtin_saveregs}. This code will be moved to the -very beginning of the function, before any parameter access are made. -The return value of this function should be an RTX that contains the -value to use as the return of @code{__builtin_saveregs}. - -@findex SETUP_INCOMING_VARARGS -@item SETUP_INCOMING_VARARGS (@var{args_so_far}, @var{mode}, @var{type}, @var{pretend_args_size}, @var{second_time}) -This macro offers an alternative to using @code{__builtin_saveregs} and -defining the macro @code{EXPAND_BUILTIN_SAVEREGS}. Use it to store the -anonymous register arguments into the stack so that all the arguments -appear to have been passed consecutively on the stack. Once this is -done, you can use the standard implementation of varargs that works for -machines that pass all their arguments on the stack. - -The argument @var{args_so_far} is the @code{CUMULATIVE_ARGS} data +@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN_SAVEREGS (void) +If defined, this hook produces the machine-specific code for a call to +@code{__builtin_saveregs}. This code will be moved to the very +beginning of the function, before any parameter access are made. The +return value of this function should be an RTX that contains the value +to use as the return of @code{__builtin_saveregs}. +@end deftypefn + +@deftypefn {Target Hook} void TARGET_SETUP_INCOMING_VARARGS (CUMULATIVE_ARGS *@var{args_so_far}, enum machine_mode @var{mode}, tree @var{type}, int *@var{pretend_args_size}, int @var{second_time}) +This target hook offers an alternative to using +@code{__builtin_saveregs} and defining the hook +@code{TARGET_EXPAND_BUILTIN_SAVEREGS}. Use it to store the anonymous +register arguments into the stack so that all the arguments appear to +have been passed consecutively on the stack. Once this is done, you can +use the standard implementation of varargs that works for machines that +pass all their arguments on the stack. + +The argument @var{args_so_far} points to the @code{CUMULATIVE_ARGS} data structure, containing the values that are obtained after processing the named arguments. The arguments @var{mode} and @var{type} describe the last named argument---its machine mode and its data type as a tree node. -The macro implementation should do two things: first, push onto the -stack all the argument registers @emph{not} used for the named -arguments, and second, store the size of the data thus pushed into the -@code{int}-valued variable whose name is supplied as the argument -@var{pretend_args_size}. The value that you store here will serve as -additional offset for setting up the stack frame. +The target hook should do two things: first, push onto the stack all the +argument registers @emph{not} used for the named arguments, and second, +store the size of the data thus pushed into the @code{int}-valued +variable pointed to by @var{pretend_args_size}. The value that you +store here will serve as additional offset for setting up the stack +frame. Because you must generate code to push the anonymous arguments at compile time without knowing their data types, -@code{SETUP_INCOMING_VARARGS} is only useful on machines that have just -a single category of argument register and use it uniformly for all data -types. +@code{TARGET_SETUP_INCOMING_VARARGS} is only useful on machines that +have just a single category of argument register and use it uniformly +for all data types. If the argument @var{second_time} is nonzero, it means that the arguments of the function are being analyzed for the second time. This happens for an inline function, which is not actually compiled until the -end of the source file. The macro @code{SETUP_INCOMING_VARARGS} should +end of the source file. The hook @code{TARGET_SETUP_INCOMING_VARARGS} should not generate any instructions in this case. +@end deftypefn -@findex STRICT_ARGUMENT_NAMING -@item STRICT_ARGUMENT_NAMING -Define this macro to be a nonzero value if the location where a function +@deftypefn {Target Hook} bool TARGET_STRICT_ARGUMENT_NAMING (CUMULATIVE_ARGS *@var{ca}) +Define this hook to return @code{true} if the location where a function argument is passed depends on whether or not it is a named argument. -This macro controls how the @var{named} argument to @code{FUNCTION_ARG} -is set for varargs and stdarg functions. If this macro returns a -nonzero value, the @var{named} argument is always true for named -arguments, and false for unnamed arguments. If it returns a value of -zero, but @code{SETUP_INCOMING_VARARGS} is defined, then all arguments -are treated as named. Otherwise, all named arguments except the last -are treated as named. +This hook controls how the @var{named} argument to @code{FUNCTION_ARG} +is set for varargs and stdarg functions. If this hook returns +@code{true}, the @var{named} argument is always true for named +arguments, and false for unnamed arguments. If it returns @code{false}, +but @code{TARGET_PRETEND_OUTOGOING_VARARGS_NAMED} returns @code{true}, +then all arguments are treated as named. Otherwise, all named arguments +except the last are treated as named. -You need not define this macro if it always returns zero. +You need not define this hook if it always returns zero. +@end deftypefn -@findex PRETEND_OUTGOING_VARARGS_NAMED -@item PRETEND_OUTGOING_VARARGS_NAMED +@deftypefn {Target Hook} bool TARGET_PRETEND_OUTGOING_VARARGS_NAMED If you need to conditionally change ABIs so that one works with -@code{SETUP_INCOMING_VARARGS}, but the other works like neither -@code{SETUP_INCOMING_VARARGS} nor @code{STRICT_ARGUMENT_NAMING} was -defined, then define this macro to return nonzero if -@code{SETUP_INCOMING_VARARGS} is used, zero otherwise. -Otherwise, you should not define this macro. -@end table +@code{TARGET_SETUP_INCOMING_VARARGS}, but the other works like neither +@code{TARGET_SETUP_INCOMING_VARARGS} nor @code{TARGET_STRICT_ARGUMENT_NAMING} was +defined, then define this hook to return @code{true} if +@code{SETUP_INCOMING_VARARGS} is used, @code{false} otherwise. +Otherwise, you should not define this hook. +@end deftypefn @node Trampolines @section Trampolines for Nested Functions @@ -4447,9 +4571,7 @@ proper offset from the start of the trampoline. On a RISC machine, it may be necessary to take out pieces of the address and store them separately. -@table @code -@findex TRAMPOLINE_TEMPLATE -@item TRAMPOLINE_TEMPLATE (@var{file}) +@defmac TRAMPOLINE_TEMPLATE (@var{file}) A C statement to output, on the stream @var{file}, assembler code for a block of data that contains the constant parts of a trampoline. This code should not include a label---the label is taken care of @@ -4459,35 +4581,35 @@ If you do not define this macro, it means no template is needed for the target. Do not define this macro on systems where the block move code to copy the trampoline into place would be larger than the code to generate it on the spot. +@end defmac -@findex TRAMPOLINE_SECTION -@item TRAMPOLINE_SECTION +@defmac TRAMPOLINE_SECTION The name of a subroutine to switch to the section in which the trampoline template is to be placed (@pxref{Sections}). The default is a value of @samp{readonly_data_section}, which places the trampoline in the section containing read-only data. +@end defmac -@findex TRAMPOLINE_SIZE -@item TRAMPOLINE_SIZE +@defmac TRAMPOLINE_SIZE A C expression for the size in bytes of the trampoline, as an integer. +@end defmac -@findex TRAMPOLINE_ALIGNMENT -@item TRAMPOLINE_ALIGNMENT +@defmac TRAMPOLINE_ALIGNMENT Alignment required for trampolines, in bits. If you don't define this macro, the value of @code{BIGGEST_ALIGNMENT} is used for aligning trampolines. +@end defmac -@findex INITIALIZE_TRAMPOLINE -@item INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain}) +@defmac INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain}) A C statement to initialize the variable parts of a trampoline. @var{addr} is an RTX for the address of the trampoline; @var{fnaddr} is an RTX for the address of the nested function; @var{static_chain} is an RTX for the static chain value that should be passed to the function when it is called. +@end defmac -@findex TRAMPOLINE_ADJUST_ADDRESS -@item TRAMPOLINE_ADJUST_ADDRESS (@var{addr}) +@defmac TRAMPOLINE_ADJUST_ADDRESS (@var{addr}) A C statement that should perform any machine-specific adjustment in the address of the trampoline. Its argument contains the address that was passed to @code{INITIALIZE_TRAMPOLINE}. In case the address to be @@ -4496,12 +4618,6 @@ the template was stored, the different address should be assigned to @var{addr}. If this macro is not defined, @var{addr} will be used for function calls. -@findex ALLOCATE_TRAMPOLINE -@item ALLOCATE_TRAMPOLINE (@var{fp}) -A C expression to allocate run-time space for a trampoline. The -expression value should be an RTX representing a memory reference to the -space for the trampoline. - @cindex @code{TARGET_ASM_FUNCTION_EPILOGUE} and trampolines @cindex @code{TARGET_ASM_FUNCTION_PROLOGUE} and trampolines If this macro is not defined, by default the trampoline is allocated as @@ -4513,12 +4629,11 @@ and @code{TARGET_ASM_FUNCTION_EPILOGUE}. @var{fp} points to a data structure, a @code{struct function}, which describes the compilation status of the immediate containing function of -the function which the trampoline is for. Normally (when -@code{ALLOCATE_TRAMPOLINE} is not defined), the stack slot for the +the function which the trampoline is for. The stack slot for the trampoline is in the stack frame of this containing function. Other allocation strategies probably must do something analogous with this information. -@end table +@end defmac Implementing trampolines is difficult on many machines because they have separate instruction and data caches. Writing into a stack location @@ -4532,40 +4647,27 @@ subroutine. The former technique makes trampoline execution faster; the latter makes initialization faster. To clear the instruction cache when a trampoline is initialized, define -the following macros which describe the shape of the cache. - -@table @code -@findex INSN_CACHE_SIZE -@item INSN_CACHE_SIZE -The total size in bytes of the cache. - -@findex INSN_CACHE_LINE_WIDTH -@item INSN_CACHE_LINE_WIDTH -The length in bytes of each cache line. The cache is divided into cache -lines which are disjoint slots, each holding a contiguous chunk of data -fetched from memory. Each time data is brought into the cache, an -entire line is read at once. The data loaded into a cache line is -always aligned on a boundary equal to the line size. - -@findex INSN_CACHE_DEPTH -@item INSN_CACHE_DEPTH -The number of alternative cache lines that can hold any particular memory -location. -@end table - -Alternatively, if the machine has system calls or instructions to clear -the instruction cache directly, you can define the following macro. - -@table @code -@findex CLEAR_INSN_CACHE -@item CLEAR_INSN_CACHE (@var{beg}, @var{end}) +the following macro. + +@defmac CLEAR_INSN_CACHE (@var{beg}, @var{end}) If defined, expands to a C expression clearing the @emph{instruction -cache} in the specified interval. If it is not defined, and the macro -@code{INSN_CACHE_SIZE} is defined, some generic code is generated to clear the -cache. The definition of this macro would typically be a series of -@code{asm} statements. Both @var{beg} and @var{end} are both pointer -expressions. -@end table +cache} in the specified interval. The definition of this macro would +typically be a series of @code{asm} statements. Both @var{beg} and +@var{end} are both pointer expressions. +@end defmac + +The operating system may also require the stack to be made executable +before calling the trampoline. To implement this requirement, define +the following macro. + +@defmac ENABLE_EXECUTE_STACK +Define this macro if certain operations must be performed before executing +code located on the stack. The macro should expand to a series of C +file-scope constructs (e.g. functions) and provide a unique entry point +named @code{__enable_execute_stack}. The target is responsible for +emitting calls to the entry point in the code, for example from the +@code{INITIALIZE_TRAMPOLINE} macro. +@end defmac To use a standard subroutine, define the following macro. In addition, you must make sure that the instructions in a trampoline fill an entire @@ -4573,9 +4675,7 @@ cache line with identical instructions, or else ensure that the beginning of the trampoline code is always aligned at the same point in its cache line. Look in @file{m68k.h} as a guide. -@table @code -@findex TRANSFER_FROM_TRAMPOLINE -@item TRANSFER_FROM_TRAMPOLINE +@defmac TRANSFER_FROM_TRAMPOLINE Define this macro if trampolines need a special subroutine to do their work. The macro should expand to a series of @code{asm} statements which will be compiled with GCC@. They go in a library function named @@ -4587,7 +4687,7 @@ special label of your own in the assembler code. Use one @code{asm} statement to generate an assembler label, and another to make the label global. Then trampolines can use that label to jump directly to your special assembler code. -@end table +@end defmac @node Library Calls @section Implicit Calls to Library Routines @@ -4597,102 +4697,59 @@ special assembler code. @c prevent bad page break with this line Here is an explanation of implicit calls to library routines. -@table @code -@findex MULSI3_LIBCALL -@item MULSI3_LIBCALL -A C string constant giving the name of the function to call for -multiplication of one signed full-word by another. If you do not -define this macro, the default name is used, which is @code{__mulsi3}, -a function defined in @file{libgcc.a}. - -@findex DIVSI3_LIBCALL -@item DIVSI3_LIBCALL -A C string constant giving the name of the function to call for -division of one signed full-word by another. If you do not define -this macro, the default name is used, which is @code{__divsi3}, a -function defined in @file{libgcc.a}. - -@findex UDIVSI3_LIBCALL -@item UDIVSI3_LIBCALL -A C string constant giving the name of the function to call for -division of one unsigned full-word by another. If you do not define -this macro, the default name is used, which is @code{__udivsi3}, a -function defined in @file{libgcc.a}. - -@findex MODSI3_LIBCALL -@item MODSI3_LIBCALL -A C string constant giving the name of the function to call for the -remainder in division of one signed full-word by another. If you do -not define this macro, the default name is used, which is -@code{__modsi3}, a function defined in @file{libgcc.a}. - -@findex UMODSI3_LIBCALL -@item UMODSI3_LIBCALL -A C string constant giving the name of the function to call for the -remainder in division of one unsigned full-word by another. If you do -not define this macro, the default name is used, which is -@code{__umodsi3}, a function defined in @file{libgcc.a}. - -@findex MULDI3_LIBCALL -@item MULDI3_LIBCALL -A C string constant giving the name of the function to call for -multiplication of one signed double-word by another. If you do not -define this macro, the default name is used, which is @code{__muldi3}, -a function defined in @file{libgcc.a}. - -@findex DIVDI3_LIBCALL -@item DIVDI3_LIBCALL -A C string constant giving the name of the function to call for -division of one signed double-word by another. If you do not define -this macro, the default name is used, which is @code{__divdi3}, a -function defined in @file{libgcc.a}. - -@findex UDIVDI3_LIBCALL -@item UDIVDI3_LIBCALL -A C string constant giving the name of the function to call for -division of one unsigned full-word by another. If you do not define -this macro, the default name is used, which is @code{__udivdi3}, a -function defined in @file{libgcc.a}. - -@findex MODDI3_LIBCALL -@item MODDI3_LIBCALL -A C string constant giving the name of the function to call for the -remainder in division of one signed double-word by another. If you do -not define this macro, the default name is used, which is -@code{__moddi3}, a function defined in @file{libgcc.a}. - -@findex UMODDI3_LIBCALL -@item UMODDI3_LIBCALL -A C string constant giving the name of the function to call for the -remainder in division of one unsigned full-word by another. If you do -not define this macro, the default name is used, which is -@code{__umoddi3}, a function defined in @file{libgcc.a}. - -@findex DECLARE_LIBRARY_RENAMES -@item DECLARE_LIBRARY_RENAMES +@defmac DECLARE_LIBRARY_RENAMES This macro, if defined, should expand to a piece of C code that will get expanded when compiling functions for libgcc.a. It can be used to -provide alternate names for gcc's internal library functions if there +provide alternate names for GCC's internal library functions if there are ABI-mandated names that the compiler should provide. +@end defmac + +@findex init_one_libfunc +@findex set_optab_libfunc +@deftypefn {Target Hook} void TARGET_INIT_LIBFUNCS (void) +This hook should declare additional library routines or rename +existing ones, using the functions @code{set_optab_libfunc} and +@code{init_one_libfunc} defined in @file{optabs.c}. +@code{init_optabs} calls this macro after initializing all the normal +library routines. -@findex INIT_TARGET_OPTABS -@item INIT_TARGET_OPTABS -Define this macro as a C statement that declares additional library -routines renames existing ones. @code{init_optabs} calls this macro after -initializing all the normal library routines. +The default is to do nothing. Most ports don't need to define this hook. +@end deftypefn -@findex FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison}) -@item FLOAT_LIB_COMPARE_RETURNS_BOOL -Define this macro as a C statement that returns nonzero if a call to -the floating point comparison library function will return a boolean -value that indicates the result of the comparison. It should return -zero if one of gcc's own libgcc functions is called. +@defmac TARGET_FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison}) +This macro should return @code{true} if the library routine that +implements the floating point comparison operator @var{comparison} in +mode @var{mode} will return a boolean, and @var{false} if it will +return a tristate. -Most ports don't need to define this macro. +GCC's own floating point libraries return tristates from the +comparison operators, so the default returns false always. Most ports +don't need to define this macro. +@end defmac + +@cindex US Software GOFAST, floating point emulation library +@cindex floating point emulation library, US Software GOFAST +@cindex GOFAST, floating point emulation library +@findex gofast_maybe_init_libfuncs +@defmac US_SOFTWARE_GOFAST +Define this macro if your system C library uses the US Software GOFAST +library to provide floating point emulation. + +In addition to defining this macro, your architecture must set +@code{TARGET_INIT_LIBFUNCS} to @code{gofast_maybe_init_libfuncs}, or +else call that function from its version of that hook. It is defined +in @file{config/gofast.h}, which must be included by your +architecture's @file{@var{cpu}.c} file. See @file{sparc/sparc.c} for +an example. + +If this macro is defined, the +@code{TARGET_FLOAT_LIB_COMPARE_RETURNS_BOOL} target hook must return +false for @code{SFmode} and @code{DFmode} comparisons. +@end defmac -@findex TARGET_EDOM @cindex @code{EDOM}, implicit usage -@item TARGET_EDOM +@findex matherr +@defmac TARGET_EDOM The value of @code{EDOM} on the target machine, as a C integer constant expression. If you don't define this macro, GCC does not attempt to deposit the value of @code{EDOM} into @code{errno} directly. Look in @@ -4704,37 +4761,37 @@ domain errors by calling the library function and letting it report the error. If mathematical functions on your system use @code{matherr} when there is an error, then you should leave @code{TARGET_EDOM} undefined so that @code{matherr} is used normally. +@end defmac -@findex GEN_ERRNO_RTX @cindex @code{errno}, implicit usage -@item GEN_ERRNO_RTX +@defmac GEN_ERRNO_RTX Define this macro as a C expression to create an rtl expression that refers to the global ``variable'' @code{errno}. (On certain systems, @code{errno} may not actually be a variable.) If you don't define this macro, a reasonable default is used. +@end defmac -@findex TARGET_MEM_FUNCTIONS @cindex @code{bcopy}, implicit usage @cindex @code{memcpy}, implicit usage @cindex @code{memmove}, implicit usage @cindex @code{bzero}, implicit usage @cindex @code{memset}, implicit usage -@item TARGET_MEM_FUNCTIONS +@defmac TARGET_MEM_FUNCTIONS Define this macro if GCC should generate calls to the ISO C (and System V) library functions @code{memcpy}, @code{memmove} and @code{memset} rather than the BSD functions @code{bcopy} and @code{bzero}. +@end defmac + +@cindex C99 math functions, implicit usage +@defmac TARGET_C99_FUNCTIONS +When this macro is nonzero, GCC will implicitly optimize @code{sin} calls into +@code{sinf} and similarly for other functions defined by C99 standard. The +default is nonzero that should be proper value for most modern systems, however +number of existing systems lacks support for these functions in the runtime so +they needs this macro to be redefined to 0. +@end defmac -@findex LIBGCC_NEEDS_DOUBLE -@item LIBGCC_NEEDS_DOUBLE -Define this macro if @code{float} arguments cannot be passed to library -routines (so they must be converted to @code{double}). This macro -affects both how library calls are generated and how the library -routines in @file{libgcc.a} accept their arguments. It is useful on -machines where floating and fixed point arguments are passed -differently, such as the i860. - -@findex NEXT_OBJC_RUNTIME -@item NEXT_OBJC_RUNTIME +@defmac NEXT_OBJC_RUNTIME Define this macro to generate code for Objective-C message sending using the calling convention of the NeXT system. This calling convention involves passing the object, the selector and the method arguments all @@ -4742,7 +4799,7 @@ at once to the method-lookup library function. The default calling convention passes just the object and the selector to the lookup function, which returns a pointer to the method. -@end table +@end defmac @node Addressing Modes @section Addressing Modes @@ -4751,55 +4808,50 @@ to the lookup function, which returns a pointer to the method. @c prevent bad page break with this line This is about addressing modes. -@table @code -@findex HAVE_PRE_INCREMENT -@findex HAVE_PRE_DECREMENT -@findex HAVE_POST_INCREMENT -@findex HAVE_POST_DECREMENT -@item HAVE_PRE_INCREMENT -@itemx HAVE_PRE_DECREMENT -@itemx HAVE_POST_INCREMENT -@itemx HAVE_POST_DECREMENT +@defmac HAVE_PRE_INCREMENT +@defmacx HAVE_PRE_DECREMENT +@defmacx HAVE_POST_INCREMENT +@defmacx HAVE_POST_DECREMENT A C expression that is nonzero if the machine supports pre-increment, pre-decrement, post-increment, or post-decrement addressing respectively. +@end defmac -@findex HAVE_POST_MODIFY_DISP -@findex HAVE_PRE_MODIFY_DISP -@item HAVE_PRE_MODIFY_DISP -@itemx HAVE_POST_MODIFY_DISP +@defmac HAVE_PRE_MODIFY_DISP +@defmacx HAVE_POST_MODIFY_DISP A C expression that is nonzero if the machine supports pre- or post-address side-effect generation involving constants other than the size of the memory operand. +@end defmac -@findex HAVE_POST_MODIFY_REG -@findex HAVE_PRE_MODIFY_REG -@item HAVE_PRE_MODIFY_REG -@itemx HAVE_POST_MODIFY_REG +@defmac HAVE_PRE_MODIFY_REG +@defmacx HAVE_POST_MODIFY_REG A C expression that is nonzero if the machine supports pre- or post-address side-effect generation involving a register displacement. +@end defmac -@findex CONSTANT_ADDRESS_P -@item CONSTANT_ADDRESS_P (@var{x}) +@defmac CONSTANT_ADDRESS_P (@var{x}) A C expression that is 1 if the RTX @var{x} is a constant which is a valid address. On most machines, this can be defined as @code{CONSTANT_P (@var{x})}, but a few machines are more restrictive in which constant addresses are supported. +@end defmac -@findex CONSTANT_P -@code{CONSTANT_P} accepts integer-values expressions whose values are -not explicitly known, such as @code{symbol_ref}, @code{label_ref}, and -@code{high} expressions and @code{const} arithmetic expressions, in -addition to @code{const_int} and @code{const_double} expressions. +@defmac CONSTANT_P (@var{x}) +@code{CONSTANT_P}, which is defined by target-independent code, +accepts integer-values expressions whose values are not explicitly +known, such as @code{symbol_ref}, @code{label_ref}, and @code{high} +expressions and @code{const} arithmetic expressions, in addition to +@code{const_int} and @code{const_double} expressions. +@end defmac -@findex MAX_REGS_PER_ADDRESS -@item MAX_REGS_PER_ADDRESS +@defmac MAX_REGS_PER_ADDRESS A number, the maximum number of registers that can appear in a valid memory address. Note that it is up to you to specify a value equal to the maximum number that @code{GO_IF_LEGITIMATE_ADDRESS} would ever accept. +@end defmac -@findex GO_IF_LEGITIMATE_ADDRESS -@item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) +@defmac GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) A C compound statement with a conditional @code{goto @var{label};} executed if @var{x} (an RTX) is a legitimate memory address on the target machine for a memory operand of mode @var{mode}. @@ -4851,21 +4903,9 @@ into the @code{symbol_ref}, and then check for it here. When you see a @code{const}, you will have to look inside it to find the @code{symbol_ref} in order to determine the section. @xref{Assembler Format}. +@end defmac -@findex saveable_obstack -The best way to modify the name string is by adding text to the -beginning, with suitable punctuation to prevent any ambiguity. Allocate -the new name in @code{saveable_obstack}. You will have to modify -@code{ASM_OUTPUT_LABELREF} to remove and decode the added text and -output the name accordingly, and define @code{TARGET_STRIP_NAME_ENCODING} -to access the original name string. - -You can check the information stored here into the @code{symbol_ref} in -the definitions of the macros @code{GO_IF_LEGITIMATE_ADDRESS} and -@code{PRINT_OPERAND_ADDRESS}. - -@findex REG_OK_FOR_BASE_P -@item REG_OK_FOR_BASE_P (@var{x}) +@defmac REG_OK_FOR_BASE_P (@var{x}) A C expression that is nonzero if @var{x} (assumed to be a @code{reg} RTX) is valid for use as a base register. For hard registers, it should always accept those which the hardware permits and reject the @@ -4873,18 +4913,18 @@ others. Whether the macro accepts or rejects pseudo registers must be controlled by @code{REG_OK_STRICT} as described above. This usually requires two variant definitions, of which @code{REG_OK_STRICT} controls the one actually used. +@end defmac -@findex REG_MODE_OK_FOR_BASE_P -@item REG_MODE_OK_FOR_BASE_P (@var{x}, @var{mode}) +@defmac REG_MODE_OK_FOR_BASE_P (@var{x}, @var{mode}) A C expression that is just like @code{REG_OK_FOR_BASE_P}, except that that expression may examine the mode of the memory reference in @var{mode}. You should define this macro if the mode of the memory reference affects whether a register may be used as a base register. If you define this macro, the compiler will use it instead of @code{REG_OK_FOR_BASE_P}. +@end defmac -@findex REG_OK_FOR_INDEX_P -@item REG_OK_FOR_INDEX_P (@var{x}) +@defmac REG_OK_FOR_INDEX_P (@var{x}) A C expression that is nonzero if @var{x} (assumed to be a @code{reg} RTX) is valid for use as an index register. @@ -4896,9 +4936,9 @@ labeling is used must fit the machine's constraints of which registers may serve in each capacity. The compiler will try both labelings, looking for one that is valid, and will reload one or both registers only if neither labeling works. +@end defmac -@findex FIND_BASE_TERM -@item FIND_BASE_TERM (@var{x}) +@defmac FIND_BASE_TERM (@var{x}) A C expression to determine the base term of address @var{x}. This macro is used in only one place: `find_base_term' in alias.c. @@ -4907,16 +4947,16 @@ that alias analysis can understand machine-dependent addresses. The typical use of this macro is to handle addresses containing a label_ref or symbol_ref within an UNSPEC@. +@end defmac -@findex LEGITIMIZE_ADDRESS -@item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) +@defmac LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) A C compound statement that attempts to replace @var{x} with a valid memory address for an operand of mode @var{mode}. @var{win} will be a C statement label elsewhere in the code; the macro definition may use -@example +@smallexample GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win}); -@end example +@end smallexample @noindent to avoid further processing if the address has become legitimate. @@ -4934,9 +4974,9 @@ It is not necessary for this macro to come up with a legitimate address. The compiler has standard ways of doing so in all cases. In fact, it is safe for this macro to do nothing. But often a machine-dependent strategy can generate better code. +@end defmac -@findex LEGITIMIZE_RELOAD_ADDRESS -@item LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win}) +@defmac LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win}) A C compound statement that attempts to replace @var{x}, which is an address that needs reloading, with a valid memory address for an operand of mode @var{mode}. @var{win} will be a C statement label elsewhere in the code. @@ -4983,9 +5023,9 @@ single level of rtl. Thus, if the part to be changed is not at the top level, you'll need to replace first the top level. It is not necessary for this macro to come up with a legitimate address; but often a machine-dependent strategy can generate better code. +@end defmac -@findex GO_IF_MODE_DEPENDENT_ADDRESS -@item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) +@defmac GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) A C statement or compound statement with a conditional @code{goto @var{label};} executed if memory address @var{x} (an RTX) can have different meanings depending on the machine mode of the memory @@ -4998,15 +5038,15 @@ of the operand being addressed. Some machines have other mode-dependent addresses. Many RISC machines have no mode-dependent addresses. You may assume that @var{addr} is a valid address for the machine. +@end defmac -@findex LEGITIMATE_CONSTANT_P -@item LEGITIMATE_CONSTANT_P (@var{x}) +@defmac LEGITIMATE_CONSTANT_P (@var{x}) A C expression that is nonzero if @var{x} is a legitimate constant for an immediate operand on the target machine. You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not check this. In fact, @samp{1} is a suitable definition for this macro on machines where anything @code{CONSTANT_P} is valid. -@end table +@end defmac @node Condition Code @section Condition Code Status @@ -5026,25 +5066,23 @@ Sometimes additional machine-specific flags must be defined in the machine description header file. It can also add additional machine-specific information by defining @code{CC_STATUS_MDEP}. -@table @code -@findex CC_STATUS_MDEP -@item CC_STATUS_MDEP +@defmac CC_STATUS_MDEP C code for a data type which is used for declaring the @code{mdep} component of @code{cc_status}. It defaults to @code{int}. This macro is not used on machines that do not use @code{cc0}. +@end defmac -@findex CC_STATUS_MDEP_INIT -@item CC_STATUS_MDEP_INIT +@defmac CC_STATUS_MDEP_INIT A C expression to initialize the @code{mdep} field to ``empty''. The default definition does nothing, since most machines don't use the field anyway. If you want to use the field, you should probably define this macro to initialize it. This macro is not used on machines that do not use @code{cc0}. +@end defmac -@findex NOTICE_UPDATE_CC -@item NOTICE_UPDATE_CC (@var{exp}, @var{insn}) +@defmac NOTICE_UPDATE_CC (@var{exp}, @var{insn}) A C compound statement to set the components of @code{cc_status} appropriately for an insn @var{insn} whose body is @var{exp}. It is this macro's responsibility to recognize insns that set the condition @@ -5079,34 +5117,9 @@ A possible definition of @code{NOTICE_UPDATE_CC} is to call a function that looks at an attribute (@pxref{Insn Attributes}) named, for example, @samp{cc}. This avoids having detailed information about patterns in two places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. +@end defmac -@findex EXTRA_CC_MODES -@item EXTRA_CC_MODES -Condition codes are represented in registers by machine modes of class -@code{MODE_CC}. By default, there is just one mode, @code{CCmode}, with -this class. If you need more such modes, create a file named -@file{@var{machine}-modes.def} in your @file{config/@var{machine}} -directory (@pxref{Back End, , Anatomy of a Target Back End}), containing -a list of these modes. Each entry in the list should be a call to the -macro @code{CC}. This macro takes one argument, which is the name of -the mode: it should begin with @samp{CC}. Do not put quotation marks -around the name, or include the trailing @samp{mode}; these are -automatically added. There should not be anything else in the file -except comments. - -A sample @file{@var{machine}-modes.def} file might look like this: - -@smallexample -CC (CC_NOOV) /* @r{Comparison only valid if there was no overflow.} */ -CC (CCFP) /* @r{Floating point comparison that cannot trap.} */ -CC (CCFPE) /* @r{Floating point comparison that may trap.} */ -@end smallexample - -When you create this file, the macro @code{EXTRA_CC_MODES} is -automatically defined by @command{configure}, with value @samp{1}. - -@findex SELECT_CC_MODE -@item SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) +@defmac SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) Returns a mode from class @code{MODE_CC} to be used when comparison operation code @var{op} is applied to rtx @var{x} and @var{y}. For example, on the SPARC, @code{SELECT_CC_MODE} is defined as (see @@ -5122,10 +5135,11 @@ definition) ? CC_NOOVmode : CCmode)) @end smallexample -You need not define this macro if @code{EXTRA_CC_MODES} is not defined. +You should define this macro if and only if you define extra CC modes +in @file{@var{machine}-modes.def}. +@end defmac -@findex CANONICALIZE_COMPARISON -@item CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) +@defmac CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) On some machines not all possible comparisons are defined, but you can convert an invalid comparison into a valid one. For example, the Alpha does not have a @code{GT} comparison, but you can use an @code{LT} @@ -5143,9 +5157,9 @@ valid but will see if the resulting insn matches a pattern in the You need not define this macro if it would never change the comparison code or operands. +@end defmac -@findex REVERSIBLE_CC_MODE -@item REVERSIBLE_CC_MODE (@var{mode}) +@defmac REVERSIBLE_CC_MODE (@var{mode}) A C expression whose value is one if it is always safe to reverse a comparison whose mode is @var{mode}. If @code{SELECT_CC_MODE} can ever return @var{mode} for a floating-point inequality comparison, @@ -5159,8 +5173,9 @@ inequality comparisons are always given @code{CCFPEmode}: @smallexample #define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode) @end smallexample +@end defmac -@findex REVERSE_CONDITION (@var{code}, @var{mode}) +@defmac REVERSE_CONDITION (@var{code}, @var{mode}) A C expression whose value is reversed condition code of the @var{code} for comparison done in CC_MODE @var{mode}. The macro is used only in case @code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case @@ -5174,9 +5189,9 @@ like: ((MODE) != CCFPmode ? reverse_condition (CODE) \ : reverse_condition_maybe_unordered (CODE)) @end smallexample +@end defmac -@findex REVERSE_CONDEXEC_PREDICATES_P -@item REVERSE_CONDEXEC_PREDICATES_P (@var{code1}, @var{code2}) +@defmac REVERSE_CONDEXEC_PREDICATES_P (@var{code1}, @var{code2}) A C expression that returns true if the conditional execution predicate @var{code1} is the inverse of @var{code2} and vice versa. Define this to return 0 if the target has conditional execution predicates that cannot be @@ -5187,8 +5202,35 @@ follows: #define REVERSE_CONDEXEC_PREDICATES_P (x, y) \ ((x) == reverse_condition (y)) @end smallexample +@end defmac -@end table +@deftypefn {Target Hook} bool TARGET_FIXED_CONDITION_CODE_REGS (unsigned int *, unsigned int *) +On targets which do not use @code{(cc0)}, and which use a hard +register rather than a pseudo-register to hold condition codes, the +regular CSE passes are often not able to identify cases in which the +hard register is set to a common value. Use this hook to enable a +small pass which optimizes such cases. This hook should return true +to enable this pass, and it should set the integers to which its +arguments point to the hard register numbers used for condition codes. +When there is only one such register, as is true on most systems, the +integer pointed to by the second argument should be set to +@code{INVALID_REGNUM}. + +The default version of this hook returns false. +@end deftypefn + +@deftypefn {Target Hook} enum machine_mode TARGET_CC_MODES_COMPATIBLE (enum machine_mode, enum machine_mode) +On targets which use multiple condition code modes in class +@code{MODE_CC}, it is sometimes the case that a comparison can be +validly done in more than one mode. On such a system, define this +target hook to take two mode arguments and to return a mode in which +both comparisons may be validly done. If there is no such mode, +return @code{VOIDmode}. + +The default version of this hook checks whether the modes are the +same. If they are, it returns that mode. If they are different, it +returns @code{VOIDmode}. +@end deftypefn @node Costs @section Describing Relative Costs of Operations @@ -5199,94 +5241,7 @@ follows: These macros let you describe the relative speed of various operations on the target machine. -@table @code -@findex CONST_COSTS -@item CONST_COSTS (@var{x}, @var{code}, @var{outer_code}) -A part of a C @code{switch} statement that describes the relative costs -of constant RTL expressions. It must contain @code{case} labels for -expression codes @code{const_int}, @code{const}, @code{symbol_ref}, -@code{label_ref} and @code{const_double}. Each case must ultimately -reach a @code{return} statement to return the relative cost of the use -of that kind of constant value in an expression. The cost may depend on -the precise value of the constant, which is available for examination in -@var{x}, and the rtx code of the expression in which it is contained, -found in @var{outer_code}. - -@var{code} is the expression code---redundant, since it can be -obtained with @code{GET_CODE (@var{x})}. - -@findex RTX_COSTS -@findex COSTS_N_INSNS -@item RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) -Like @code{CONST_COSTS} but applies to nonconstant RTL expressions. -This can be used, for example, to indicate how costly a multiply -instruction is. In writing this macro, you can use the construct -@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast -instructions. @var{outer_code} is the code of the expression in which -@var{x} is contained. - -This macro is optional; do not define it if the default cost assumptions -are adequate for the target machine. - -@findex DEFAULT_RTX_COSTS -@item DEFAULT_RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) -This macro, if defined, is called for any case not handled by the -@code{RTX_COSTS} or @code{CONST_COSTS} macros. This eliminates the need -to put case labels into the macro, but the code, or any functions it -calls, must assume that the RTL in @var{x} could be of any type that has -not already been handled. The arguments are the same as for -@code{RTX_COSTS}, and the macro should execute a return statement giving -the cost of any RTL expressions that it can handle. The default cost -calculation is used for any RTL for which this macro does not return a -value. - -This macro is optional; do not define it if the default cost assumptions -are adequate for the target machine. - -@findex ADDRESS_COST -@item ADDRESS_COST (@var{address}) -An expression giving the cost of an addressing mode that contains -@var{address}. If not defined, the cost is computed from -the @var{address} expression and the @code{CONST_COSTS} values. - -For most CISC machines, the default cost is a good approximation of the -true cost of the addressing mode. However, on RISC machines, all -instructions normally have the same length and execution time. Hence -all addresses will have equal costs. - -In cases where more than one form of an address is known, the form with -the lowest cost will be used. If multiple forms have the same, lowest, -cost, the one that is the most complex will be used. - -For example, suppose an address that is equal to the sum of a register -and a constant is used twice in the same basic block. When this macro -is not defined, the address will be computed in a register and memory -references will be indirect through that register. On machines where -the cost of the addressing mode containing the sum is no higher than -that of a simple indirect reference, this will produce an additional -instruction and possibly require an additional register. Proper -specification of this macro eliminates this overhead for such machines. - -Similar use of this macro is made in strength reduction of loops. - -@var{address} need not be valid as an address. In such a case, the cost -is not relevant and can be any value; invalid addresses need not be -assigned a different cost. - -On machines where an address involving more than one register is as -cheap as an address computation involving only one register, defining -@code{ADDRESS_COST} to reflect this can cause two registers to be live -over a region of code where only one would have been if -@code{ADDRESS_COST} were not defined in that manner. This effect should -be considered in the definition of this macro. Equivalent costs should -probably only be given to addresses with different numbers of registers -on machines with lots of registers. - -This macro will normally either not be defined or be defined as a -constant. - -@findex REGISTER_MOVE_COST -@item REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to}) +@defmac REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to}) A C expression for the cost of moving data of mode @var{mode} from a register in class @var{from} to one in class @var{to}. The classes are expressed using the enumeration values such as @code{GENERAL_REGS}. A @@ -5303,9 +5258,9 @@ classes returns a value of 2, reload does not check to ensure that the constraints of the insn are met. Setting a cost of other than 2 will allow reload to verify that the constraints are met. You should do this if the @samp{mov@var{m}} pattern's constraints do not allow such copying. +@end defmac -@findex MEMORY_MOVE_COST -@item MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in}) +@defmac MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in}) A C expression for the cost of moving data of mode @var{mode} between a register of class @var{class} and memory; @var{in} is zero if the value is to be written to memory, nonzero if it is to be read in. This cost @@ -5327,20 +5282,18 @@ secondary register in the conventional way but the default base value of 4 is not correct for your machine, define this macro to add some other value to the result of that function. The arguments to that function are the same as to this macro. +@end defmac -@findex BRANCH_COST -@item BRANCH_COST +@defmac BRANCH_COST A C expression for the cost of a branch instruction. A value of 1 is the default; other values are interpreted relative to that. -@end table +@end defmac Here are additional macros which do not specify precise relative costs, but only that certain actions are more expensive than GCC would ordinarily expect. -@table @code -@findex SLOW_BYTE_ACCESS -@item SLOW_BYTE_ACCESS +@defmac SLOW_BYTE_ACCESS Define this macro as a C expression which is nonzero if accessing less than a word of memory (i.e.@: a @code{char} or a @code{short}) is no faster than accessing a word of memory, i.e., if such access @@ -5353,9 +5306,9 @@ load will be used if alignment permits. Unless bytes accesses are faster than word accesses, using word accesses is preferable since it may eliminate subsequent memory access if subsequent accesses occur to other fields in the same word of the structure, but to different bytes. +@end defmac -@findex SLOW_UNALIGNED_ACCESS -@item SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment}) +@defmac SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment}) Define this macro to be the value 1 if memory accesses described by the @var{mode} and @var{alignment} parameters have a cost many times greater than aligned accesses, for example if they are emulated in a trap @@ -5370,15 +5323,9 @@ cycle or two to the time for a memory access. If the value of this macro is always zero, it need not be defined. If this macro is defined, it should produce a nonzero value when @code{STRICT_ALIGNMENT} is nonzero. +@end defmac -@findex DONT_REDUCE_ADDR -@item DONT_REDUCE_ADDR -Define this macro to inhibit strength reduction of memory addresses. -(On some machines, such strength reduction seems to do harm rather -than good.) - -@findex MOVE_RATIO -@item MOVE_RATIO +@defmac MOVE_RATIO The threshold of number of scalar memory-to-memory move insns, @emph{below} which a sequence of insns should be generated instead of a string move insn or a library call. Increasing the value will always @@ -5389,94 +5336,165 @@ Note that on machines where the corresponding move insn is a the number of such sequences. If you don't define this, a reasonable default is used. +@end defmac -@findex MOVE_BY_PIECES_P -@item MOVE_BY_PIECES_P (@var{size}, @var{alignment}) +@defmac MOVE_BY_PIECES_P (@var{size}, @var{alignment}) A C expression used to determine whether @code{move_by_pieces} will be used to copy a chunk of memory, or whether some other block move mechanism will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less than @code{MOVE_RATIO}. +@end defmac -@findex MOVE_MAX_PIECES -@item MOVE_MAX_PIECES +@defmac MOVE_MAX_PIECES A C expression used by @code{move_by_pieces} to determine the largest unit a load or store used to copy memory is. Defaults to @code{MOVE_MAX}. +@end defmac -@findex CLEAR_RATIO -@item CLEAR_RATIO +@defmac CLEAR_RATIO The threshold of number of scalar move insns, @emph{below} which a sequence of insns should be generated to clear memory instead of a string clear insn or a library call. Increasing the value will always make code faster, but eventually incurs high cost in increased code size. If you don't define this, a reasonable default is used. +@end defmac -@findex CLEAR_BY_PIECES_P -@item CLEAR_BY_PIECES_P (@var{size}, @var{alignment}) +@defmac CLEAR_BY_PIECES_P (@var{size}, @var{alignment}) A C expression used to determine whether @code{clear_by_pieces} will be used to clear a chunk of memory, or whether some other block clear mechanism will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less than @code{CLEAR_RATIO}. +@end defmac + +@defmac STORE_BY_PIECES_P (@var{size}, @var{alignment}) +A C expression used to determine whether @code{store_by_pieces} will be +used to set a chunk of memory to a constant value, or whether some other +mechanism will be used. Used by @code{__builtin_memset} when storing +values other than constant zero and by @code{__builtin_strcpy} when +when called with a constant source string. +Defaults to @code{MOVE_BY_PIECES_P}. +@end defmac -@findex USE_LOAD_POST_INCREMENT -@item USE_LOAD_POST_INCREMENT (@var{mode}) +@defmac USE_LOAD_POST_INCREMENT (@var{mode}) A C expression used to determine whether a load postincrement is a good thing to use for a given mode. Defaults to the value of @code{HAVE_POST_INCREMENT}. +@end defmac -@findex USE_LOAD_POST_DECREMENT -@item USE_LOAD_POST_DECREMENT (@var{mode}) +@defmac USE_LOAD_POST_DECREMENT (@var{mode}) A C expression used to determine whether a load postdecrement is a good thing to use for a given mode. Defaults to the value of @code{HAVE_POST_DECREMENT}. +@end defmac -@findex USE_LOAD_PRE_INCREMENT -@item USE_LOAD_PRE_INCREMENT (@var{mode}) +@defmac USE_LOAD_PRE_INCREMENT (@var{mode}) A C expression used to determine whether a load preincrement is a good thing to use for a given mode. Defaults to the value of @code{HAVE_PRE_INCREMENT}. +@end defmac -@findex USE_LOAD_PRE_DECREMENT -@item USE_LOAD_PRE_DECREMENT (@var{mode}) +@defmac USE_LOAD_PRE_DECREMENT (@var{mode}) A C expression used to determine whether a load predecrement is a good thing to use for a given mode. Defaults to the value of @code{HAVE_PRE_DECREMENT}. +@end defmac -@findex USE_STORE_POST_INCREMENT -@item USE_STORE_POST_INCREMENT (@var{mode}) +@defmac USE_STORE_POST_INCREMENT (@var{mode}) A C expression used to determine whether a store postincrement is a good thing to use for a given mode. Defaults to the value of @code{HAVE_POST_INCREMENT}. +@end defmac -@findex USE_STORE_POST_DECREMENT -@item USE_STORE_POST_DECREMENT (@var{mode}) +@defmac USE_STORE_POST_DECREMENT (@var{mode}) A C expression used to determine whether a store postdecrement is a good thing to use for a given mode. Defaults to the value of @code{HAVE_POST_DECREMENT}. +@end defmac -@findex USE_STORE_PRE_INCREMENT -@item USE_STORE_PRE_INCREMENT (@var{mode}) +@defmac USE_STORE_PRE_INCREMENT (@var{mode}) This macro is used to determine whether a store preincrement is a good thing to use for a given mode. Defaults to the value of @code{HAVE_PRE_INCREMENT}. +@end defmac -@findex USE_STORE_PRE_DECREMENT -@item USE_STORE_PRE_DECREMENT (@var{mode}) +@defmac USE_STORE_PRE_DECREMENT (@var{mode}) This macro is used to determine whether a store predecrement is a good thing to use for a given mode. Defaults to the value of @code{HAVE_PRE_DECREMENT}. +@end defmac -@findex NO_FUNCTION_CSE -@item NO_FUNCTION_CSE +@defmac NO_FUNCTION_CSE Define this macro if it is as good or better to call a constant function address than to call an address kept in a register. +@end defmac -@findex NO_RECURSIVE_FUNCTION_CSE -@item NO_RECURSIVE_FUNCTION_CSE +@defmac NO_RECURSIVE_FUNCTION_CSE Define this macro if it is as good or better for a function to call itself with an explicit address than to call an address kept in a register. -@end table +@end defmac + +@defmac RANGE_TEST_NON_SHORT_CIRCUIT +Define this macro if a non-short-circuit operation produced by +@samp{fold_range_test ()} is optimal. This macro defaults to true if +@code{BRANCH_COST} is greater than or equal to the value 2. +@end defmac + +@deftypefn {Target Hook} bool TARGET_RTX_COSTS (rtx @var{x}, int @var{code}, int @var{outer_code}, int *@var{total}) +This target hook describes the relative costs of RTL expressions. + +The cost may depend on the precise form of the expression, which is +available for examination in @var{x}, and the rtx code of the expression +in which it is contained, found in @var{outer_code}. @var{code} is the +expression code---redundant, since it can be obtained with +@code{GET_CODE (@var{x})}. + +In implementing this hook, you can use the construct +@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast +instructions. + +On entry to the hook, @code{*@var{total}} contains a default estimate +for the cost of the expression. The hook should modify this value as +necessary. + +The hook returns true when all subexpressions of @var{x} have been +processed, and false when @code{rtx_cost} should recurse. +@end deftypefn + +@deftypefn {Target Hook} int TARGET_ADDRESS_COST (rtx @var{address}) +This hook computes the cost of an addressing mode that contains +@var{address}. If not defined, the cost is computed from +the @var{address} expression and the @code{TARGET_RTX_COST} hook. + +For most CISC machines, the default cost is a good approximation of the +true cost of the addressing mode. However, on RISC machines, all +instructions normally have the same length and execution time. Hence +all addresses will have equal costs. + +In cases where more than one form of an address is known, the form with +the lowest cost will be used. If multiple forms have the same, lowest, +cost, the one that is the most complex will be used. + +For example, suppose an address that is equal to the sum of a register +and a constant is used twice in the same basic block. When this macro +is not defined, the address will be computed in a register and memory +references will be indirect through that register. On machines where +the cost of the addressing mode containing the sum is no higher than +that of a simple indirect reference, this will produce an additional +instruction and possibly require an additional register. Proper +specification of this macro eliminates this overhead for such machines. + +This hook is never called with an invalid address. + +On machines where an address involving more than one register is as +cheap as an address computation involving only one register, defining +@code{TARGET_ADDRESS_COST} to reflect this can cause two registers to +be live over a region of code where only one would have been if +@code{TARGET_ADDRESS_COST} were not defined in that manner. This effect +should be considered in the definition of this macro. Equivalent costs +should probably only be given to addresses with different numbers of +registers on machines with lots of registers. +@end deftypefn @node Scheduling @section Adjusting the Instruction Scheduler @@ -5504,13 +5522,15 @@ to return the value of the macro @code{MAX_DFA_ISSUE_RATE}. @deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx @var{insn}, int @var{more}) This hook is executed by the scheduler after it has scheduled an insn from the ready list. It should return the number of insns which can -still be issued in the current cycle. Normally this is -@samp{@w{@var{more} - 1}}. You should define this hook if some insns -take more machine resources than others, so that fewer insns can follow -them in the same cycle. @var{file} is either a null pointer, or a stdio -stream to write any debug output to. @var{verbose} is the verbose level -provided by @option{-fsched-verbose-@var{n}}. @var{insn} is the -instruction that was scheduled. +still be issued in the current cycle. The default is +@samp{@w{@var{more} - 1}} for insns other than @code{CLOBBER} and +@code{USE}, which normally are not counted against the issue rate. +You should define this hook if some insns take more machine resources +than others, so that fewer insns can follow them in the same cycle. +@var{file} is either a null pointer, or a stdio stream to write any +debug output to. @var{verbose} is the verbose level provided by +@option{-fsched-verbose-@var{n}}. @var{insn} is the instruction that +was scheduled. @end deftypefn @deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx @var{insn}, rtx @var{link}, rtx @var{dep_insn}, int @var{cost}) @@ -5564,6 +5584,16 @@ scheduling one insn causes other insns to become ready in the same cycle. These other insns can then be taken into account properly. @end deftypefn +@deftypefn {Target Hook} void TARGET_SCHED_DEPENDENCIES_EVALUATION_HOOK (rtx @var{head}, rtx @var{tail}) +This hook is called after evaluation forward dependencies of insns in +chain given by two parameter values (@var{head} and @var{tail} +correspondingly) but before insns scheduling of the insn chain. For +example, it can be used for better insn classification if it requires +analysis of dependencies. This hook can use backward and forward +dependencies of the insn scheduler because they are already +calculated. +@end deftypefn + @deftypefn {Target Hook} void TARGET_SCHED_INIT (FILE *@var{file}, int @var{verbose}, int @var{max_ready}) This hook is executed by the scheduler at the beginning of each block of instructions that are to be scheduled. @var{file} is either a null @@ -5650,6 +5680,30 @@ schedules to choose the best one. The default is no multipass scheduling. @end deftypefn +@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD (rtx) + +This hook controls what insns from the ready insn queue will be +considered for the multipass insn scheduling. If the hook returns +zero for insn passed as the parameter, the insn will be not chosen to +be issued. + +The default is that any ready insns can be chosen to be issued. +@end deftypefn + +@deftypefn {Target Hook} int TARGET_SCHED_DFA_NEW_CYCLE (FILE *, int, rtx, int, int, int *) + +This hook is called by the insn scheduler before issuing insn passed +as the third parameter on given cycle. If the hook returns nonzero, +the insn is not issued on given processors cycle. Instead of that, +the processor cycle is advanced. If the value passed through the last +parameter is zero, the insn ready queue is not sorted on the new cycle +start as usually. The first parameter passes file for debugging +output. The second one passes the scheduler verbose level of the +debugging output. The forth and the fifth parameter values are +correspondingly processor cycle on which the previous insn has been +issued and the current processor cycle. +@end deftypefn + @deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_BUBBLES (void) The @acronym{DFA}-based scheduler could take the insertion of nop operations for better insn scheduling into account. It can be done @@ -5685,37 +5739,56 @@ zero. The hook should return @code{NULL} if there are no more nop insns with indexes greater than given index. @end deftypefn +@deftypefn {Target Hook} bool IS_COSTLY_DEPENDENCE (rtx @var{insn1}, rtx @var{insn2}, rtx @var{dep_link}, int @var{dep_cost}, int @var{distance}) +This hook is used to define which dependences are considered costly by +the target, so costly that it is not advisable to schedule the insns that +are involved in the dependence too close to one another. The parameters +to this hook are as follows: The second parameter @var{insn2} is dependent +upon the first parameter @var{insn1}. The dependence between @var{insn1} +and @var{insn2} is represented by the third parameter @var{dep_link}. The +fourth parameter @var{cost} is the cost of the dependence, and the fifth +parameter @var{distance} is the distance in cycles between the two insns. +The hook returns @code{true} if considering the distance between the two +insns the dependence between them is considered costly by the target, +and @code{false} otherwise. + +Defining this hook can be useful in multiple-issue out-of-order machines, +where (a) it's practically hopeless to predict the actual data/resource +delays, however: (b) there's a better chance to predict the actual grouping +that will be formed, and (c) correctly emulating the grouping can be very +important. In such targets one may want to allow issuing dependent insns +closer to one another - i.e, closer than the dependence distance; however, +not in cases of "costly dependences", which this hooks allows to define. +@end deftypefn + Macros in the following table are generated by the program @file{genattr} and can be useful for writing the hooks. -@table @code -@findex TRADITIONAL_PIPELINE_INTERFACE -@item TRADITIONAL_PIPELINE_INTERFACE +@defmac TRADITIONAL_PIPELINE_INTERFACE The macro definition is generated if there is a traditional pipeline description in @file{.md} file. You should also remember that to simplify the insn scheduler sources an empty traditional pipeline description interface is generated even if there is no a traditional pipeline description in the @file{.md} file. The macro can be used to distinguish the two types of the traditional interface. +@end defmac -@findex DFA_PIPELINE_INTERFACE -@item DFA_PIPELINE_INTERFACE +@defmac DFA_PIPELINE_INTERFACE The macro definition is generated if there is an automaton pipeline description in @file{.md} file. You should also remember that to simplify the insn scheduler sources an empty automaton pipeline description interface is generated even if there is no an automaton pipeline description in the @file{.md} file. The macro can be used to distinguish the two types of the automaton interface. +@end defmac -@findex MAX_DFA_ISSUE_RATE -@item MAX_DFA_ISSUE_RATE +@defmac MAX_DFA_ISSUE_RATE The macro definition is generated in the automaton based pipeline description interface. Its value is calculated from the automaton based pipeline description and is equal to maximal number of all insns described in constructions @samp{define_insn_reservation} which can be issued on the same processor cycle. - -@end table +@end defmac @node Sections @section Dividing the Output into Sections (Texts, Data, @dots{}) @@ -5733,45 +5806,36 @@ The compiler must tell the assembler when to switch sections. These macros control what commands to output to tell the assembler this. You can also define additional sections. -@table @code -@findex TEXT_SECTION_ASM_OP -@item TEXT_SECTION_ASM_OP +@defmac TEXT_SECTION_ASM_OP A C expression whose value is a string, including spacing, containing the assembler operation that should precede instructions and read-only data. Normally @code{"\t.text"} is right. +@end defmac -@findex TEXT_SECTION -@item TEXT_SECTION -A C statement that switches to the default section containing instructions. -Normally this is not needed, as simply defining @code{TEXT_SECTION_ASM_OP} -is enough. The MIPS port uses this to sort all functions after all data -declarations. - -@findex HOT_TEXT_SECTION_NAME -@item HOT_TEXT_SECTION_NAME +@defmac HOT_TEXT_SECTION_NAME If defined, a C string constant for the name of the section containing most frequently executed functions of the program. If not defined, GCC will provide a default definition if the target supports named sections. +@end defmac -@findex UNLIKELY_EXECUTED_TEXT_SECTION_NAME -@item UNLIKELY_EXECUTED_TEXT_SECTION_NAME +@defmac UNLIKELY_EXECUTED_TEXT_SECTION_NAME If defined, a C string constant for the name of the section containing unlikely executed functions in the program. +@end defmac -@findex DATA_SECTION_ASM_OP -@item DATA_SECTION_ASM_OP +@defmac DATA_SECTION_ASM_OP A C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as writable initialized data. Normally @code{"\t.data"} is right. +@end defmac -@findex READONLY_DATA_SECTION_ASM_OP -@item READONLY_DATA_SECTION_ASM_OP +@defmac READONLY_DATA_SECTION_ASM_OP A C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as read-only initialized data. +@end defmac -@findex READONLY_DATA_SECTION -@item READONLY_DATA_SECTION +@defmac READONLY_DATA_SECTION A macro naming a function to call to switch to the proper section for read-only data. The default is to use @code{READONLY_DATA_SECTION_ASM_OP} if defined, else fall back to @code{text_section}. @@ -5779,15 +5843,15 @@ if defined, else fall back to @code{text_section}. The most common definition will be @code{data_section}, if the target does not have a special read-only data section, and does not put data in the text section. +@end defmac -@findex SHARED_SECTION_ASM_OP -@item SHARED_SECTION_ASM_OP +@defmac SHARED_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as shared data. If not defined, @code{DATA_SECTION_ASM_OP} will be used. +@end defmac -@findex BSS_SECTION_ASM_OP -@item BSS_SECTION_ASM_OP +@defmac BSS_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as uninitialized global data. If not defined, and neither @@ -5795,30 +5859,23 @@ uninitialized global data. If not defined, and neither uninitialized global data will be output in the data section if @option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be used. +@end defmac -@findex SHARED_BSS_SECTION_ASM_OP -@item SHARED_BSS_SECTION_ASM_OP -If defined, a C expression whose value is a string, including spacing, -containing the assembler operation to identify the following data as -uninitialized global shared data. If not defined, and -@code{BSS_SECTION_ASM_OP} is, the latter will be used. - -@findex INIT_SECTION_ASM_OP -@item INIT_SECTION_ASM_OP +@defmac INIT_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as initialization code. If not defined, GCC will assume such a section does not exist. +@end defmac -@findex FINI_SECTION_ASM_OP -@item FINI_SECTION_ASM_OP +@defmac FINI_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as finalization code. If not defined, GCC will assume such a section does not exist. +@end defmac -@findex CRT_CALL_STATIC_FUNCTION -@item CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function}) +@defmac CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function}) If defined, an ASM statement that switches to a different section via @var{section_op}, calls @var{function}, and switches back to the text section. This is used in @file{crtstuff.c} if @@ -5828,40 +5885,40 @@ sections. By default, this macro uses a simple function call. Some ports need hand-crafted assembly code to avoid dependencies on registers initialized in the function prologue or to ensure that constant pools don't end up too far way in the text section. +@end defmac -@findex FORCE_CODE_SECTION_ALIGN -@item FORCE_CODE_SECTION_ALIGN +@defmac FORCE_CODE_SECTION_ALIGN If defined, an ASM statement that aligns a code section to some arbitrary boundary. This is used to force all fragments of the @code{.init} and @code{.fini} sections to have to same alignment and thus prevent the linker from having to add any padding. +@end defmac -@findex EXTRA_SECTIONS @findex in_text @findex in_data -@item EXTRA_SECTIONS +@defmac EXTRA_SECTIONS A list of names for sections other than the standard two, which are @code{in_text} and @code{in_data}. You need not define this macro on a system with no other sections (that GCC needs to use). +@end defmac -@findex EXTRA_SECTION_FUNCTIONS @findex text_section @findex data_section -@item EXTRA_SECTION_FUNCTIONS +@defmac EXTRA_SECTION_FUNCTIONS One or more functions to be defined in @file{varasm.c}. These functions should do jobs analogous to those of @code{text_section} and @code{data_section}, for your additional sections. Do not define this macro if you do not define @code{EXTRA_SECTIONS}. +@end defmac -@findex JUMP_TABLES_IN_TEXT_SECTION -@item JUMP_TABLES_IN_TEXT_SECTION +@defmac JUMP_TABLES_IN_TEXT_SECTION Define this macro to be an expression with a nonzero value if jump tables (for @code{tablejump} insns) should be output in the text section, along with the assembler instructions. Otherwise, the readonly data section is used. This macro is irrelevant if there is no separate readonly data section. -@end table +@end defmac @deftypefn {Target Hook} void TARGET_ASM_SELECT_SECTION (tree @var{exp}, int @var{reloc}, unsigned HOST_WIDE_INT @var{align}) Switches to the appropriate section for output of @var{exp}. You can @@ -5902,30 +5959,42 @@ constants in @code{flag_pic} mode in @code{data_section} and everything else in @code{readonly_data_section}. @end deftypefn -@deftypefn {Target Hook} void TARGET_ENCODE_SECTION_INFO (tree @var{decl}, int @var{new_decl_p}) +@deftypefn {Target Hook} void TARGET_ENCODE_SECTION_INFO (tree @var{decl}, rtx @var{rtl}, int @var{new_decl_p}) Define this hook if references to a symbol or a constant must be treated differently depending on something about the variable or function named by the symbol (such as what section it is in). -The hook is executed under two circumstances. One is immediately after -the rtl for @var{decl} that represents a variable or a function has been -created and stored in @code{DECL_RTL(@var{decl})}. The value of the rtl -will be a @code{mem} whose address is a @code{symbol_ref}. The other is -immediately after the rtl for @var{decl} that represents a constant has -been created and stored in @code{TREE_CST_RTL (@var{decl})}. The macro -is called once for each distinct constant in a source file. +The hook is executed immediately after rtl has been created for +@var{decl}, which may be a variable or function declaration or +an entry in the constant pool. In either case, @var{rtl} is the +rtl in question. Do @emph{not} use @code{DECL_RTL (@var{decl})} +in this hook; that field may not have been initialized yet. + +In the case of a constant, it is safe to assume that the rtl is +a @code{mem} whose address is a @code{symbol_ref}. Most decls +will also have this form, but that is not guaranteed. Global +register variables, for instance, will have a @code{reg} for their +rtl. (Normally the right thing to do with such unusual rtl is +leave it alone.) The @var{new_decl_p} argument will be true if this is the first time -that @code{ENCODE_SECTION_INFO} has been invoked on this decl. It will +that @code{TARGET_ENCODE_SECTION_INFO} has been invoked on this decl. It will be false for subsequent invocations, which will happen for duplicate declarations. Whether or not anything must be done for the duplicate declaration depends on whether the hook examines @code{DECL_ATTRIBUTES}. +@var{new_decl_p} is always true when the hook is called for a constant. @cindex @code{SYMBOL_REF_FLAG}, in @code{TARGET_ENCODE_SECTION_INFO} -The usual thing for this hook to do is to record a flag in the -@code{symbol_ref} (such as @code{SYMBOL_REF_FLAG}) or to store a -modified name string in the @code{symbol_ref} (if one bit is not -enough information). +The usual thing for this hook to do is to record flags in the +@code{symbol_ref}, using @code{SYMBOL_REF_FLAG} or @code{SYMBOL_REF_FLAGS}. +Historically, the name string was modified if it was necessary to +encode more than one bit of information, but this practice is now +discouraged; use @code{SYMBOL_REF_FLAGS}. + +The default definition of this hook, @code{default_encode_section_info} +in @file{varasm.c}, sets a number of commonly-useful bits in +@code{SYMBOL_REF_FLAGS}. Check whether the default does what you need +before overriding it. @end deftypefn @deftypefn {Target Hook} const char *TARGET_STRIP_NAME_ENCODING (const char *name) @@ -5976,9 +6045,7 @@ switch statements so that they use relative addresses. @c i rearranged the order of the macros above to try to force one of @c them to the next line, to eliminate an overfull hbox. --mew 10feb93 -@table @code -@findex PIC_OFFSET_TABLE_REGNUM -@item PIC_OFFSET_TABLE_REGNUM +@defmac PIC_OFFSET_TABLE_REGNUM The register number of the register used to address a table of static data addresses in memory. In some cases this register is defined by a processor's ``application binary interface'' (ABI)@. When this macro @@ -5987,15 +6054,15 @@ pointer and frame pointer registers. If this macro is not defined, it is up to the machine-dependent files to allocate such a register (if necessary). Note that this register must be fixed when in use (e.g.@: when @code{flag_pic} is true). +@end defmac -@findex PIC_OFFSET_TABLE_REG_CALL_CLOBBERED -@item PIC_OFFSET_TABLE_REG_CALL_CLOBBERED +@defmac PIC_OFFSET_TABLE_REG_CALL_CLOBBERED Define this macro if the register defined by @code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. Do not define this macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined. +@end defmac -@findex FINALIZE_PIC -@item FINALIZE_PIC +@defmac FINALIZE_PIC By generating position-independent code, when two different programs (A and B) share a common library (libC.a), the text of the library can be shared whether or not the library is linked at the same address for both @@ -6009,9 +6076,9 @@ before. (It is not done before, because in the case of compiling an inline function, it would lead to multiple PIC prologues being included in functions which used inline functions and were compiled to assembly language.) +@end defmac -@findex LEGITIMATE_PIC_OPERAND_P -@item LEGITIMATE_PIC_OPERAND_P (@var{x}) +@defmac LEGITIMATE_PIC_OPERAND_P (@var{x}) A C expression that is nonzero if @var{x} is a legitimate immediate operand on the target machine when generating position independent code. You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not @@ -6019,7 +6086,7 @@ check this. You can also assume @var{flag_pic} is true, so you need not check it either. You need not define this macro if all constants (including @code{SYMBOL_REF}) can be immediate operands when generating position independent code. -@end table +@end defmac @node Assembler Format @section Defining the Output Assembler Language @@ -6050,93 +6117,107 @@ instructions do. @cindex output of assembler code @c prevent bad page break with this line -This describes the overall framework of an assembler file. - -@table @code -@findex ASM_FILE_START -@item ASM_FILE_START (@var{stream}) -A C expression which outputs to the stdio stream @var{stream} -some appropriate text to go at the start of an assembler file. - -Normally this macro is defined to output a line containing -@samp{#NO_APP}, which is a comment that has no effect on most -assemblers but tells the GNU assembler that it can save time by not -checking for certain assembler constructs. +This describes the overall framework of an assembly file. + +@deftypefn {Target Hook} void TARGET_ASM_FILE_START () +@findex default_file_start +Output to @code{asm_out_file} any text which the assembler expects to +find at the beginning of a file. The default behavior is controlled +by two flags, documented below. Unless your target's assembler is +quite unusual, if you override the default, you should call +@code{default_file_start} at some point in your target hook. This +lets other target files rely on these variables. +@end deftypefn -On systems that use SDB, it is necessary to output certain commands; -see @file{attasm.h}. +@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_APP_OFF +If this flag is true, the text of the macro @code{ASM_APP_OFF} will be +printed as the very first line in the assembly file, unless +@option{-fverbose-asm} is in effect. (If that macro has been defined +to the empty string, this variable has no effect.) With the normal +definition of @code{ASM_APP_OFF}, the effect is to notify the GNU +assembler that it need not bother stripping comments or extra +whitespace from its input. This allows it to work a bit faster. + +The default is false. You should not set it to true unless you have +verified that your port does not generate any extra whitespace or +comments that will cause GAS to issue errors in NO_APP mode. +@end deftypevr -@findex ASM_FILE_END -@item ASM_FILE_END (@var{stream}) -A C expression which outputs to the stdio stream @var{stream} -some appropriate text to go at the end of an assembler file. +@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_FILE_DIRECTIVE +If this flag is true, @code{output_file_directive} will be called +for the primary source file, immediately after printing +@code{ASM_APP_OFF} (if that is enabled). Most ELF assemblers expect +this to be done. The default is false. +@end deftypevr -If this macro is not defined, the default is to output nothing -special at the end of the file. Most systems don't require any -definition. +@deftypefn {Target Hook} void TARGET_ASM_FILE_END () +Output to @code{asm_out_file} any text which the assembler expects +to find at the end of a file. The default is to output nothing. +@end deftypefn -On systems that use SDB, it is necessary to output certain commands; -see @file{attasm.h}. +@deftypefun void file_end_indicate_exec_stack () +Some systems use a common convention, the @samp{.note.GNU-stack} +special section, to indicate whether or not an object file relies on +the stack being executable. If your system uses this convention, you +should define @code{TARGET_ASM_FILE_END} to this function. If you +need to do other things in that hook, have your hook function call +this function. +@end deftypefun -@findex ASM_COMMENT_START -@item ASM_COMMENT_START +@defmac ASM_COMMENT_START A C string constant describing how to begin a comment in the target assembler language. The compiler assumes that the comment will end at the end of the line. +@end defmac -@findex ASM_APP_ON -@item ASM_APP_ON +@defmac ASM_APP_ON A C string constant for text to be output before each @code{asm} statement or group of consecutive ones. Normally this is @code{"#APP"}, which is a comment that has no effect on most assemblers but tells the GNU assembler that it must check the lines that follow for all valid assembler constructs. +@end defmac -@findex ASM_APP_OFF -@item ASM_APP_OFF +@defmac ASM_APP_OFF A C string constant for text to be output after each @code{asm} statement or group of consecutive ones. Normally this is @code{"#NO_APP"}, which tells the GNU assembler to resume making the time-saving assumptions that are valid for ordinary compiler output. +@end defmac -@findex ASM_OUTPUT_SOURCE_FILENAME -@item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) +@defmac ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) A C statement to output COFF information or DWARF debugging information which indicates that filename @var{name} is the current source file to the stdio stream @var{stream}. This macro need not be defined if the standard form of output for the file format in use is appropriate. +@end defmac -@findex OUTPUT_QUOTED_STRING -@item OUTPUT_QUOTED_STRING (@var{stream}, @var{string}) +@defmac OUTPUT_QUOTED_STRING (@var{stream}, @var{string}) A C statement to output the string @var{string} to the stdio stream @var{stream}. If you do not call the function @code{output_quoted_string} in your config files, GCC will only call it to output filenames to the assembler source. So you can use it to canonicalize the format of the filename using this macro. +@end defmac -@findex ASM_OUTPUT_SOURCE_LINE -@item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) +@defmac ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}, @var{counter}) A C statement to output DBX or SDB debugging information before code for line number @var{line} of the current source file to the -stdio stream @var{stream}. +stdio stream @var{stream}. @var{counter} is the number of time the +macro was invoked, including the current invocation; it is intended +to generate unique labels in the assembly output. This macro need not be defined if the standard form of debugging information for the debugger in use is appropriate. +@end defmac -@findex ASM_OUTPUT_IDENT -@item ASM_OUTPUT_IDENT (@var{stream}, @var{string}) +@defmac ASM_OUTPUT_IDENT (@var{stream}, @var{string}) A C statement to output something to the assembler file to handle a @samp{#ident} directive containing the text @var{string}. If this macro is not defined, nothing is output for a @samp{#ident} directive. - -@findex OBJC_PROLOGUE -@item OBJC_PROLOGUE -A C statement to output any assembler statements which are required to -precede any Objective-C object definitions or message sending. The -statement is executed only when compiling an Objective-C program. -@end table +@end defmac @deftypefn {Target Hook} void TARGET_ASM_NAMED_SECTION (const char *@var{name}, unsigned int @var{flags}, unsigned int @var{align}) Output assembly directives to switch to section @var{name}. The section @@ -6202,9 +6283,7 @@ The default implementation of this hook will use the when the relevant string is @code{NULL}. @end deftypefn -@table @code -@findex OUTPUT_ADDR_CONST_EXTRA -@item OUTPUT_ADDR_CONST_EXTRA (@var{stream}, @var{x}, @var{fail}) +@defmac OUTPUT_ADDR_CONST_EXTRA (@var{stream}, @var{x}, @var{fail}) A C statement to recognize @var{rtx} patterns that @code{output_addr_const} can't deal with, and output assembly code to @var{stream} corresponding to the pattern @var{x}. This may be used to @@ -6214,9 +6293,9 @@ If @code{OUTPUT_ADDR_CONST_EXTRA} fails to recognize a pattern, it must @code{goto fail}, so that a standard error message is printed. If it prints an error message itself, by calling, for example, @code{output_operand_lossage}, it may just complete normally. +@end defmac -@findex ASM_OUTPUT_ASCII -@item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) +@defmac ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) A C statement to output to the stdio stream @var{stream} an assembler instruction to assemble a string constant containing the @var{len} bytes at @var{ptr}. @var{ptr} will be a C expression of type @@ -6225,24 +6304,24 @@ bytes at @var{ptr}. @var{ptr} will be a C expression of type If the assembler has a @code{.ascii} pseudo-op as found in the Berkeley Unix assembler, do not define the macro @code{ASM_OUTPUT_ASCII}. +@end defmac -@findex ASM_OUTPUT_FDESC -@item ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n}) +@defmac ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n}) A C statement to output word @var{n} of a function descriptor for @var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS} is defined, and is otherwise unused. +@end defmac -@findex CONSTANT_POOL_BEFORE_FUNCTION -@item CONSTANT_POOL_BEFORE_FUNCTION +@defmac CONSTANT_POOL_BEFORE_FUNCTION You may define this macro as a C expression. You should define the expression to have a nonzero value if GCC should output the constant pool for a function before the code for the function, or a zero value if GCC should output the constant pool after the function. If you do not define this macro, the usual case, GCC will output the constant pool before the function. +@end defmac -@findex ASM_OUTPUT_POOL_PROLOGUE -@item ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size}) +@defmac ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size}) A C statement to output assembler commands to define the start of the constant pool for a function. @var{funname} is a string giving the name of the function. Should the return type of the function @@ -6252,9 +6331,9 @@ immediately after this call. If no constant-pool prefix is required, the usual case, this macro need not be defined. +@end defmac -@findex ASM_OUTPUT_SPECIAL_POOL_ENTRY -@item ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) +@defmac ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) A C statement (with or without semicolon) to output a constant in the constant pool, if it needs special treatment. (This macro need not do anything for RTL expressions that can be output normally.) @@ -6271,25 +6350,18 @@ the address of this pool entry. The definition of this macro is responsible for outputting the label definition at the proper place. Here is how to do this: -@example -ASM_OUTPUT_INTERNAL_LABEL (@var{file}, "LC", @var{labelno}); -@end example +@smallexample +@code{(*targetm.asm_out.internal_label)} (@var{file}, "LC", @var{labelno}); +@end smallexample When you output a pool entry specially, you should end with a @code{goto} to the label @var{jumpto}. This will prevent the same pool entry from being output a second time in the usual manner. You need not define this macro if it would do nothing. +@end defmac -@findex CONSTANT_AFTER_FUNCTION_P -@item CONSTANT_AFTER_FUNCTION_P (@var{exp}) -Define this macro as a C expression which is nonzero if the constant -@var{exp}, of type @code{tree}, should be output after the code for a -function. The compiler will normally output all constants before the -function; you need not define this macro if this is OK@. - -@findex ASM_OUTPUT_POOL_EPILOGUE -@item ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) +@defmac ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) A C statement to output assembler commands to at the end of the constant pool for a function. @var{funname} is a string giving the name of the function. Should the return type of the function be required, you can @@ -6298,15 +6370,15 @@ constant pool that GCC wrote immediately before this call. If no constant-pool epilogue is required, the usual case, you need not define this macro. +@end defmac -@findex IS_ASM_LOGICAL_LINE_SEPARATOR -@item IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}) +@defmac IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}) Define this macro as a C expression which is nonzero if @var{C} is used as a logical line separator by the assembler. If you do not define this macro, the default is that only the character @samp{;} is treated as a logical line separator. -@end table +@end defmac @deftypevr {Target Hook} {const char *} TARGET_ASM_OPEN_PAREN @deftypevrx {Target Hook} {const char *} TARGET_ASM_CLOSE_PAREN @@ -6318,13 +6390,9 @@ default to normal parentheses, which is correct for most assemblers. These macros are provided by @file{real.h} for writing the definitions of @code{ASM_OUTPUT_DOUBLE} and the like: -@table @code -@item REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) -@itemx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) -@itemx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) -@findex REAL_VALUE_TO_TARGET_SINGLE -@findex REAL_VALUE_TO_TARGET_DOUBLE -@findex REAL_VALUE_TO_TARGET_LONG_DOUBLE +@defmac REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) +@defmacx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) +@defmacx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the target's floating point representation, and store its bit pattern in the variable @var{l}. For @code{REAL_VALUE_TO_TARGET_SINGLE}, this variable should @@ -6338,7 +6406,7 @@ host machine. The array element values are designed so that you can print them out using @code{fprintf} in the order they should appear in the target machine's memory. -@end table +@end defmac @node Uninitialized Data @subsection Output of Uninitialized Variables @@ -6346,9 +6414,7 @@ machine's memory. Each of the macros in this section is used to do the whole job of outputting a single uninitialized variable. -@table @code -@findex ASM_OUTPUT_COMMON -@item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) +@defmac ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) A C statement (sans semicolon) to output to the stdio stream @var{stream} the assembler definition of a common-label named @var{name} whose size is @var{size} bytes. The variable @var{rounded} @@ -6360,32 +6426,32 @@ assembler syntax for defining the name, and a newline. This macro controls how the assembler definitions of uninitialized common global variables are output. +@end defmac -@findex ASM_OUTPUT_ALIGNED_COMMON -@item ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) +@defmac ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a separate, explicit argument. If you define this macro, it is used in place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in handling the required alignment of the variable. The alignment is specified as the number of bits. +@end defmac -@findex ASM_OUTPUT_ALIGNED_DECL_COMMON -@item ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) +@defmac ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) Like @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the variable to be output, if there is one, or @code{NULL_TREE} if there is no corresponding variable. If you define this macro, GCC will use it in place of both @code{ASM_OUTPUT_COMMON} and @code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see the variable's decl in order to chose what to output. +@end defmac -@findex ASM_OUTPUT_SHARED_COMMON -@item ASM_OUTPUT_SHARED_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) +@defmac ASM_OUTPUT_SHARED_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) If defined, it is similar to @code{ASM_OUTPUT_COMMON}, except that it is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_COMMON} will be used. +@end defmac -@findex ASM_OUTPUT_BSS -@item ASM_OUTPUT_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) +@defmac ASM_OUTPUT_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) A C statement (sans semicolon) to output to the stdio stream @var{stream} the assembler definition of uninitialized global @var{decl} named @var{name} whose size is @var{size} bytes. The variable @var{rounded} @@ -6404,9 +6470,9 @@ is not defined for all targets. If this macro and @code{ASM_OUTPUT_ALIGNED_BSS} are not defined then @code{ASM_OUTPUT_COMMON} or @code{ASM_OUTPUT_ALIGNED_COMMON} or @code{ASM_OUTPUT_ALIGNED_DECL_COMMON} is used. +@end defmac -@findex ASM_OUTPUT_ALIGNED_BSS -@item ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) +@defmac ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) Like @code{ASM_OUTPUT_BSS} except takes the required alignment as a separate, explicit argument. If you define this macro, it is used in place of @code{ASM_OUTPUT_BSS}, and gives you more flexibility in @@ -6415,15 +6481,15 @@ as the number of bits. Try to use function @code{asm_output_aligned_bss} defined in file @file{varasm.c} when defining this macro. +@end defmac -@findex ASM_OUTPUT_SHARED_BSS -@item ASM_OUTPUT_SHARED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) +@defmac ASM_OUTPUT_SHARED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) If defined, it is similar to @code{ASM_OUTPUT_BSS}, except that it is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_BSS} will be used. +@end defmac -@findex ASM_OUTPUT_LOCAL -@item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) +@defmac ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) A C statement (sans semicolon) to output to the stdio stream @var{stream} the assembler definition of a local-common-label named @var{name} whose size is @var{size} bytes. The variable @var{rounded} @@ -6435,30 +6501,30 @@ assembler syntax for defining the name, and a newline. This macro controls how the assembler definitions of uninitialized static variables are output. +@end defmac -@findex ASM_OUTPUT_ALIGNED_LOCAL -@item ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) +@defmac ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a separate, explicit argument. If you define this macro, it is used in place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in handling the required alignment of the variable. The alignment is specified as the number of bits. +@end defmac -@findex ASM_OUTPUT_ALIGNED_DECL_LOCAL -@item ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) +@defmac ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) Like @code{ASM_OUTPUT_ALIGNED_DECL} except that @var{decl} of the variable to be output, if there is one, or @code{NULL_TREE} if there is no corresponding variable. If you define this macro, GCC will use it in place of both @code{ASM_OUTPUT_DECL} and @code{ASM_OUTPUT_ALIGNED_DECL}. Define this macro when you need to see the variable's decl in order to chose what to output. +@end defmac -@findex ASM_OUTPUT_SHARED_LOCAL -@item ASM_OUTPUT_SHARED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) +@defmac ASM_OUTPUT_SHARED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) If defined, it is similar to @code{ASM_OUTPUT_LOCAL}, except that it is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_LOCAL} will be used. -@end table +@end defmac @node Label Output @subsection Output and Generation of Labels @@ -6466,19 +6532,17 @@ will be used. @c prevent bad page break with this line This is about outputting labels. -@table @code -@findex ASM_OUTPUT_LABEL @findex assemble_name -@item ASM_OUTPUT_LABEL (@var{stream}, @var{name}) +@defmac ASM_OUTPUT_LABEL (@var{stream}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @var{stream} the assembler definition of a label named @var{name}. Use the expression @code{assemble_name (@var{stream}, @var{name})} to output the name itself; before and after that, output the additional assembler syntax for defining the name, and a newline. A default definition of this macro is provided which is correct for most systems. +@end defmac -@findex SIZE_ASM_OP -@item SIZE_ASM_OP +@defmac SIZE_ASM_OP A C string containing the appropriate assembler directive to specify the size of a symbol, without any arguments. On systems that use ELF, the default (in @file{config/elfos.h}) is @samp{"\t.size\t"}; on other @@ -6489,21 +6553,21 @@ of @code{ASM_OUTPUT_SIZE_DIRECTIVE} and @code{ASM_OUTPUT_MEASURED_SIZE} for your system. If you need your own custom definitions of those macros, or if you do not need explicit symbol sizes at all, do not define this macro. +@end defmac -@findex ASM_OUTPUT_SIZE_DIRECTIVE -@item ASM_OUTPUT_SIZE_DIRECTIVE (@var{stream}, @var{name}, @var{size}) +@defmac ASM_OUTPUT_SIZE_DIRECTIVE (@var{stream}, @var{name}, @var{size}) A C statement (sans semicolon) to output to the stdio stream @var{stream} a directive telling the assembler that the size of the symbol @var{name} is @var{size}. @var{size} is a @code{HOST_WIDE_INT}. If you define @code{SIZE_ASM_OP}, a default definition of this macro is provided. +@end defmac -@findex ASM_OUTPUT_MEASURED_SIZE -@item ASM_OUTPUT_MEASURED_SIZE (@var{stream}, @var{name}) +@defmac ASM_OUTPUT_MEASURED_SIZE (@var{stream}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @var{stream} a directive telling the assembler to calculate the size of the symbol @var{name} by subtracting its address from the current -address. +address. If you define @code{SIZE_ASM_OP}, a default definition of this macro is provided. The default assumes that the assembler recognizes a special @@ -6511,9 +6575,9 @@ provided. The default assumes that the assembler recognizes a special the difference between this and another symbol. If your assembler does not recognize @samp{.} or cannot do calculations with it, you will need to redefine @code{ASM_OUTPUT_MEASURED_SIZE} to use some other technique. +@end defmac -@findex TYPE_ASM_OP -@item TYPE_ASM_OP +@defmac TYPE_ASM_OP A C string containing the appropriate assembler directive to specify the type of a symbol, without any arguments. On systems that use ELF, the default (in @file{config/elfos.h}) is @samp{"\t.type\t"}; on other @@ -6523,9 +6587,9 @@ Define this macro only if it is correct to use the default definition of @code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own custom definition of this macro, or if you do not need explicit symbol types at all, do not define this macro. +@end defmac -@findex TYPE_OPERAND_FMT -@item TYPE_OPERAND_FMT +@defmac TYPE_OPERAND_FMT A C string which specifies (using @code{printf} syntax) the format of the second operand to @code{TYPE_ASM_OP}. On systems that use ELF, the default (in @file{config/elfos.h}) is @samp{"@@%s"}; on other systems, @@ -6535,9 +6599,9 @@ Define this macro only if it is correct to use the default definition of @code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own custom definition of this macro, or if you do not need explicit symbol types at all, do not define this macro. +@end defmac -@findex ASM_OUTPUT_TYPE_DIRECTIVE -@item ASM_OUTPUT_TYPE_DIRECTIVE (@var{stream}, @var{type}) +@defmac ASM_OUTPUT_TYPE_DIRECTIVE (@var{stream}, @var{type}) A C statement (sans semicolon) to output to the stdio stream @var{stream} a directive telling the assembler that the type of the symbol @var{name} is @var{type}. @var{type} is a C string; currently, @@ -6546,9 +6610,9 @@ you should not count on this. If you define @code{TYPE_ASM_OP} and @code{TYPE_OPERAND_FMT}, a default definition of this macro is provided. +@end defmac -@findex ASM_DECLARE_FUNCTION_NAME -@item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) +@defmac ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) A C statement (sans semicolon) to output to the stdio stream @var{stream} any text necessary for declaring the name @var{name} of a function which is being defined. This macro is responsible for @@ -6561,9 +6625,9 @@ usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition of this macro. +@end defmac -@findex ASM_DECLARE_FUNCTION_SIZE -@item ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) +@defmac ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) A C statement (sans semicolon) to output to the stdio stream @var{stream} any text necessary for declaring the size of a function which is being defined. The argument @var{name} is the name of the @@ -6574,9 +6638,9 @@ If this macro is not defined, then the function size is not defined. You may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro. +@end defmac -@findex ASM_DECLARE_OBJECT_NAME -@item ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) +@defmac ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) A C statement (sans semicolon) to output to the stdio stream @var{stream} any text necessary for declaring the name @var{name} of an initialized variable which is being defined. This macro must output the @@ -6588,9 +6652,9 @@ usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} and/or @code{ASM_OUTPUT_SIZE_DIRECTIVE} in the definition of this macro. +@end defmac -@findex ASM_DECLARE_CONSTANT_NAME -@item ASM_DECLARE_CONSTANT_NAME (@var{stream}, @var{name}, @var{exp}, @var{size}) +@defmac ASM_DECLARE_CONSTANT_NAME (@var{stream}, @var{name}, @var{exp}, @var{size}) A C statement (sans semicolon) to output to the stdio stream @var{stream} any text necessary for declaring the name @var{name} of a constant which is being defined. This macro is responsible for @@ -6604,18 +6668,18 @@ usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition of this macro. +@end defmac -@findex ASM_DECLARE_REGISTER_GLOBAL -@item ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) +@defmac ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @var{stream} any text necessary for claiming a register @var{regno} for a global variable @var{decl} with name @var{name}. If you don't define this macro, that is equivalent to defining it to do nothing. +@end defmac -@findex ASM_FINISH_DECLARE_OBJECT -@item ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) +@defmac ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) A C statement (sans semicolon) to finish up declaring a variable name once the compiler has processed its initializer fully and thus has had a chance to determine the size of an array when controlled by an @@ -6627,7 +6691,7 @@ nothing. You may wish to use @code{ASM_OUTPUT_SIZE_DIRECTIVE} and/or @code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro. -@end table +@end defmac @deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_LABEL (FILE *@var{stream}, const char *@var{name}) This target hook is a function to output to the stdio stream @@ -6638,9 +6702,7 @@ The default implementation relies on a proper definition of @code{GLOBAL_ASM_OP}. @end deftypefn -@table @code -@findex ASM_WEAKEN_LABEL -@item ASM_WEAKEN_LABEL (@var{stream}, @var{name}) +@defmac ASM_WEAKEN_LABEL (@var{stream}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @var{stream} some commands that will make the label @var{name} weak; that is, available for reference from other files but only used if @@ -6652,9 +6714,9 @@ for making that name weak, and a newline. If you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not support weak symbols and you should not define the @code{SUPPORTS_WEAK} macro. +@end defmac -@findex ASM_WEAKEN_DECL -@item ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) +@defmac ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) Combines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and @code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function or variable decl. If @var{value} is not @code{NULL}, this C statement @@ -6662,9 +6724,9 @@ should output to the stdio stream @var{stream} assembler code which defines (equates) the weak symbol @var{name} to have the value @var{value}. If @var{value} is @code{NULL}, it should output commands to make @var{name} weak. +@end defmac -@findex SUPPORTS_WEAK -@item SUPPORTS_WEAK +@defmac SUPPORTS_WEAK A C expression which evaluates to true if the target supports weak symbols. If you don't define this macro, @file{defaults.h} provides a default @@ -6672,18 +6734,18 @@ definition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL} is defined, the default definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if you want to control weak symbol support with a compiler flag such as @option{-melf}. +@end defmac -@findex MAKE_DECL_ONE_ONLY (@var{decl}) -@item MAKE_DECL_ONE_ONLY +@defmac MAKE_DECL_ONE_ONLY (@var{decl}) A C statement (sans semicolon) to mark @var{decl} to be emitted as a public symbol such that extra copies in multiple translation units will be discarded by the linker. Define this macro if your object file format provides support for this concept, such as the @samp{COMDAT} section flags in the Microsoft Windows PE/COFF format, and this support requires changes to @var{decl}, such as putting it in a separate section. +@end defmac -@findex SUPPORTS_ONE_ONLY -@item SUPPORTS_ONE_ONLY +@defmac SUPPORTS_ONE_ONLY A C expression which evaluates to true if the target supports one-only semantics. @@ -6693,6 +6755,7 @@ definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if you want to control one-only symbol support with a compiler flag, or if setting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to be emitted as one-only. +@end defmac @deftypefn {Target Hook} void TARGET_ASM_ASSEMBLE_VISIBILITY (tree @var{decl}, const char *@var{visibility}) This target hook is a function to output to @var{asm_out_file} some @@ -6700,8 +6763,7 @@ commands that will make the symbol(s) associated with @var{decl} have hidden, protected or internal visibility as specified by @var{visibility}. @end deftypefn -@findex ASM_OUTPUT_EXTERNAL -@item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) +@defmac ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @var{stream} any text necessary for declaring the name of an external symbol named @var{name} which is referenced in this compilation but @@ -6710,35 +6772,31 @@ declaration. This macro need not be defined if it does not need to output anything. The GNU assembler and most Unix assemblers don't require anything. +@end defmac -@findex ASM_OUTPUT_EXTERNAL_LIBCALL -@item ASM_OUTPUT_EXTERNAL_LIBCALL (@var{stream}, @var{symref}) -A C statement (sans semicolon) to output on @var{stream} an assembler +@deftypefn {Target Hook} void TARGET_ASM_EXTERNAL_LIBCALL (rtx @var{symref}) +This target hook is a function to output to @var{asm_out_file} an assembler pseudo-op to declare a library function name external. The name of the -library function is given by @var{symref}, which has type @code{rtx} and -is a @code{symbol_ref}. - -This macro need not be defined if it does not need to output anything. -The GNU assembler and most Unix assemblers don't require anything. +library function is given by @var{symref}, which is a @code{symbol_ref}. +@end deftypefn -@findex ASM_OUTPUT_LABELREF -@item ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) +@defmac ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @var{stream} a reference in assembler syntax to a label named @var{name}. This should add @samp{_} to the front of the name, if that is customary on your operating system, as it is in most Berkeley Unix systems. This macro is used in @code{assemble_name}. +@end defmac -@findex ASM_OUTPUT_SYMBOL_REF -@item ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) +@defmac ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) A C statement (sans semicolon) to output a reference to @code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} will be used to output the name of the symbol. This macro may be used to modify the way a symbol is referenced depending on information encoded by @code{TARGET_ENCODE_SECTION_INFO}. +@end defmac -@findex ASM_OUTPUT_LABEL_REF -@item ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) +@defmac ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) A C statement (sans semicolon) to output a reference to @var{buf}, the result of @code{ASM_GENERATE_INTERNAL_LABEL}. If not defined, @code{assemble_name} will be used to output the name of the symbol. @@ -6746,11 +6804,11 @@ This macro is not used by @code{output_asm_label}, or the @code{%l} specifier that calls it; the intention is that this macro should be set when it is necessary to output a label differently when its address is being taken. +@end defmac -@findex ASM_OUTPUT_INTERNAL_LABEL -@item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) -A C statement to output to the stdio stream @var{stream} a label whose -name is made from the string @var{prefix} and the number @var{num}. +@deftypefn {Target Hook} void TARGET_ASM_INTERNAL_LABEL (FILE *@var{stream}, const char *@var{prefix}, unsigned long @var{labelno}) +A function to output to the stdio stream @var{stream} a label whose +name is made from the string @var{prefix} and the number @var{labelno}. It is absolutely essential that these labels be distinct from the labels used for user-level functions and variables. Otherwise, certain programs @@ -6762,14 +6820,10 @@ should be excluded; on many systems, the letter @samp{L} at the beginning of a label has this effect. You should find out what convention your system uses, and follow it. -The usual definition of this macro is as follows: - -@example -fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num}) -@end example +The default version of this function utilizes ASM_GENERATE_INTERNAL_LABEL. +@end deftypefn -@findex ASM_OUTPUT_DEBUG_LABEL -@item ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) +@defmac ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) A C statement to output to the stdio stream @var{stream} a debug info label whose name is made from the string @var{prefix} and the number @var{num}. This is useful for VLIW targets, where debug info labels @@ -6778,16 +6832,16 @@ systems, branch target labels must be at the beginning of instruction bundles, but debug info labels can occur in the middle of instruction bundles. -If this macro is not defined, then @code{ASM_OUTPUT_INTERNAL_LABEL} will be +If this macro is not defined, then @code{(*targetm.asm_out.internal_label)} will be used. +@end defmac -@findex ASM_GENERATE_INTERNAL_LABEL -@item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) +@defmac ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) A C statement to store into the string @var{string} a label whose name is made from the string @var{prefix} and the number @var{num}. This string, when output subsequently by @code{assemble_name}, should -produce the output that @code{ASM_OUTPUT_INTERNAL_LABEL} would produce +produce the output that @code{(*targetm.asm_out.internal_label)} would produce with the same @var{prefix} and @var{num}. If the string begins with @samp{*}, then @code{assemble_name} will @@ -6797,9 +6851,9 @@ string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets to output the string, and may change it. (Of course, @code{ASM_OUTPUT_LABELREF} is also part of your machine description, so you should know what it does on your machine.) +@end defmac -@findex ASM_FORMAT_PRIVATE_NAME -@item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) +@defmac ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) A C expression to assign to @var{outvar} (which is a variable of type @code{char *}) a newly allocated string made from the string @var{name} and the number @var{number}, with some suitable punctuation @@ -6817,17 +6871,20 @@ conflict with the user's own symbols. Most assemblers allow periods or percent signs in assembler symbols; putting at least one of these between the name and the number will suffice. -@findex ASM_OUTPUT_DEF -@item ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) +If this macro is not defined, a default definition will be provided +which is correct for most systems. +@end defmac + +@defmac ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) A C statement to output to the stdio stream @var{stream} assembler code which defines (equates) the symbol @var{name} to have the value @var{value}. @findex SET_ASM_OP If @code{SET_ASM_OP} is defined, a default definition is provided which is correct for most systems. +@end defmac -@findex ASM_OUTPUT_DEF_FROM_DECLS -@item ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) +@defmac ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) A C statement to output to the stdio stream @var{stream} assembler code which defines (equates) the symbol whose tree node is @var{decl_of_name} to have the value of the tree node @var{decl_of_value}. This macro will @@ -6837,9 +6894,9 @@ the tree nodes are available. @findex SET_ASM_OP If @code{SET_ASM_OP} is defined, a default definition is provided which is correct for most systems. +@end defmac -@findex ASM_OUTPUT_WEAK_ALIAS -@item ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) +@defmac ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) A C statement to output to the stdio stream @var{stream} assembler code which defines (equates) the weak symbol @var{name} to have the value @var{value}. If @var{value} is @code{NULL}, it defines @var{name} as @@ -6847,9 +6904,9 @@ an undefined weak symbol. Define this macro if the target only supports weak aliases; define @code{ASM_OUTPUT_DEF} instead if possible. +@end defmac -@findex OBJC_GEN_METHOD_LABEL -@item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) +@defmac OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) Define this macro to override the default assembler names used for Objective-C methods. @@ -6874,21 +6931,21 @@ in a category); and @var{sel_name} is the name of the selector. On systems where the assembler can handle quoted names, you can use this macro to provide more human-readable names. +@end defmac -@findex ASM_DECLARE_CLASS_REFERENCE -@item ASM_DECLARE_CLASS_REFERENCE (@var{stream}, @var{name}) +@defmac ASM_DECLARE_CLASS_REFERENCE (@var{stream}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @var{stream} commands to declare that the label @var{name} is an Objective-C class reference. This is only needed for targets whose linkers have special support for NeXT-style runtimes. +@end defmac -@findex ASM_DECLARE_UNRESOLVED_REFERENCE -@item ASM_DECLARE_UNRESOLVED_REFERENCE (@var{stream}, @var{name}) +@defmac ASM_DECLARE_UNRESOLVED_REFERENCE (@var{stream}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @var{stream} commands to declare that the label @var{name} is an unresolved Objective-C class reference. This is only needed for targets whose linkers have special support for NeXT-style runtimes. -@end table +@end defmac @node Initialization @subsection How Initialization Functions Are Handled @@ -6954,9 +7011,9 @@ support a @dfn{.init} section which is executed at program startup, parts of @file{crtstuff.c} are compiled into that section. The program is linked by the @command{gcc} driver like this: -@example +@smallexample ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o -@end example +@end smallexample The prologue of a function (@code{__init}) appears in the @code{.init} section of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise @@ -7019,34 +7076,33 @@ customize the handling of initialization and termination functions. Here are the macros that control how the compiler handles initialization and termination functions: -@table @code -@findex INIT_SECTION_ASM_OP -@item INIT_SECTION_ASM_OP +@defmac INIT_SECTION_ASM_OP If defined, a C string constant, including spacing, for the assembler operation to identify the following data as initialization code. If not defined, GCC will assume such a section does not exist. When you are using special sections for initialization and termination functions, this macro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to run the initialization functions. +@end defmac -@item HAS_INIT_SECTION -@findex HAS_INIT_SECTION +@defmac HAS_INIT_SECTION If defined, @code{main} will not call @code{__main} as described above. This macro should be defined for systems that control start-up code on a symbol-by-symbol basis, such as OSF/1, and should not be defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}. +@end defmac -@item LD_INIT_SWITCH -@findex LD_INIT_SWITCH +@defmac LD_INIT_SWITCH If defined, a C string constant for a switch that tells the linker that the following symbol is an initialization routine. +@end defmac -@item LD_FINI_SWITCH -@findex LD_FINI_SWITCH +@defmac LD_FINI_SWITCH If defined, a C string constant for a switch that tells the linker that the following symbol is a finalization routine. +@end defmac -@item COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) +@defmac COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) If defined, a C statement that will write a function that can be automatically called when a shared library is loaded. The function should call @var{func}, which takes no arguments. If not defined, and @@ -7056,28 +7112,29 @@ function called @code{_GLOBAL__DI} will be generated. This function and the following one are used by collect2 when linking a shared library that needs constructors or destructors, or has DWARF2 exception tables embedded in the code. +@end defmac -@item COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) +@defmac COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) If defined, a C statement that will write a function that can be automatically called when a shared library is unloaded. The function should call @var{func}, which takes no arguments. If not defined, and the object format requires an explicit finalization function, then a function called @code{_GLOBAL__DD} will be generated. +@end defmac -@item INVOKE__main -@findex INVOKE__main +@defmac INVOKE__main If defined, @code{main} will call @code{__main} despite the presence of @code{INIT_SECTION_ASM_OP}. This macro should be defined for systems where the init section is not actually run automatically, but is still useful for collecting the lists of constructors and destructors. +@end defmac -@item SUPPORTS_INIT_PRIORITY -@findex SUPPORTS_INIT_PRIORITY +@defmac SUPPORTS_INIT_PRIORITY If nonzero, the C++ @code{init_priority} attribute is supported and the compiler should emit instructions to control the order of initialization of objects. If zero, the compiler will issue an error message upon encountering an @code{init_priority} attribute. -@end table +@end defmac @deftypefn {Target Hook} bool TARGET_HAVE_CTORS_DTORS This value is true if the target supports some ``native'' method of @@ -7112,27 +7169,25 @@ If your system uses @command{collect2} as the means of processing constructors, then that program normally uses @command{nm} to scan an object file for constructor functions to be called. -On certain kinds of systems, you can define these macros to make +On certain kinds of systems, you can define this macro to make @command{collect2} work faster (and, in some cases, make it work at all): -@table @code -@findex OBJECT_FORMAT_COFF -@item OBJECT_FORMAT_COFF +@defmac OBJECT_FORMAT_COFF Define this macro if the system uses COFF (Common Object File Format) object files, so that @command{collect2} can assume this format and scan object files directly for dynamic constructor/destructor functions. -@findex OBJECT_FORMAT_ROSE -@item OBJECT_FORMAT_ROSE -Define this macro if the system uses ROSE format object files, so that -@command{collect2} can assume this format and scan object files directly -for dynamic constructor/destructor functions. - -These macros are effective only in a native compiler; @command{collect2} as +This macro is effective only in a native compiler; @command{collect2} as part of a cross compiler always uses @command{nm} for the target machine. +@end defmac + +@defmac COLLECT_PARSE_FLAG (@var{flag}) +Define this macro to be C code that examines @command{collect2} command +line option @var{flag} and performs special actions if +@command{collect2} needs to behave differently depending on @var{flag}. +@end defmac -@findex REAL_NM_FILE_NAME -@item REAL_NM_FILE_NAME +@defmac REAL_NM_FILE_NAME Define this macro as a C string constant containing the file name to use to execute @command{nm}. The default is to search the path normally for @command{nm}. @@ -7141,21 +7196,21 @@ If your system supports shared libraries and has a program to list the dynamic dependencies of a given library or executable, you can define these macros to enable support for running initialization and termination functions in shared libraries: +@end defmac -@findex LDD_SUFFIX -@item LDD_SUFFIX +@defmac LDD_SUFFIX Define this macro to a C string constant containing the name of the program which lists dynamic dependencies, like @command{"ldd"} under SunOS 4. +@end defmac -@findex PARSE_LDD_OUTPUT -@item PARSE_LDD_OUTPUT (@var{ptr}) +@defmac PARSE_LDD_OUTPUT (@var{ptr}) Define this macro to be C code that extracts filenames from the output of the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable of type @code{char *} that points to the beginning of a line of output from @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the code must advance @var{ptr} to the beginning of the filename on that line. Otherwise, it must set @var{ptr} to @code{NULL}. -@end table +@end defmac @node Instruction Output @subsection Output of Assembler Instructions @@ -7163,22 +7218,20 @@ line. Otherwise, it must set @var{ptr} to @code{NULL}. @c prevent bad page break with this line This describes assembler instruction output. -@table @code -@findex REGISTER_NAMES -@item REGISTER_NAMES +@defmac REGISTER_NAMES A C initializer containing the assembler's names for the machine registers, each one as a C string constant. This is what translates register numbers in the compiler into assembler language. +@end defmac -@findex ADDITIONAL_REGISTER_NAMES -@item ADDITIONAL_REGISTER_NAMES +@defmac ADDITIONAL_REGISTER_NAMES If defined, a C initializer for an array of structures containing a name and a register number. This macro defines additional names for hard registers, thus allowing the @code{asm} option in declarations to refer to registers using alternate names. +@end defmac -@findex ASM_OUTPUT_OPCODE -@item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) +@defmac ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) Define this macro if you are using an unusual assembler that requires different names for the machine instructions. @@ -7203,9 +7256,9 @@ elements of @code{recog_data.operand}. If the macro definition does nothing, the instruction is output in the usual way. +@end defmac -@findex FINAL_PRESCAN_INSN -@item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) +@defmac FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) If defined, a C statement to be executed just prior to the output of assembler code for @var{insn}, to modify the extracted operands so they will be output differently. @@ -7225,15 +7278,9 @@ syntax affecting individual insn patterns ought to be handled by writing conditional output routines in those patterns. If this macro is not defined, it is equivalent to a null statement. +@end defmac -@findex FINAL_PRESCAN_LABEL -@item FINAL_PRESCAN_LABEL -If defined, @code{FINAL_PRESCAN_INSN} will be called on each -@code{CODE_LABEL}. In that case, @var{opvec} will be a null pointer and -@var{noperands} will be zero. - -@findex PRINT_OPERAND -@item PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) +@defmac PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) A C compound statement to output to stdio stream @var{stream} the assembler syntax for an instruction operand @var{x}. @var{x} is an RTL expression. @@ -7256,17 +7303,17 @@ When the machine description has a specification @samp{%@var{punct}} (a @samp{%} followed by a punctuation character), this macro is called with a null pointer for @var{x} and the punctuation character for @var{code}. +@end defmac -@findex PRINT_OPERAND_PUNCT_VALID_P -@item PRINT_OPERAND_PUNCT_VALID_P (@var{code}) +@defmac PRINT_OPERAND_PUNCT_VALID_P (@var{code}) A C expression which evaluates to true if @var{code} is a valid punctuation character for use in the @code{PRINT_OPERAND} macro. If @code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no punctuation characters (except for the standard one, @samp{%}) are used in this way. +@end defmac -@findex PRINT_OPERAND_ADDRESS -@item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) +@defmac PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) A C compound statement to output to stdio stream @var{stream} the assembler syntax for an instruction operand that is a memory reference whose address is @var{x}. @var{x} is an RTL expression. @@ -7275,11 +7322,12 @@ whose address is @var{x}. @var{x} is an RTL expression. On some machines, the syntax for a symbolic address depends on the section that the address refers to. On these machines, define the hook @code{TARGET_ENCODE_SECTION_INFO} to store the information into the -@code{symbol_ref}, and then check for it here. @xref{Assembler Format}. +@code{symbol_ref}, and then check for it here. @xref{Assembler +Format}. +@end defmac -@findex DBR_OUTPUT_SEQEND @findex dbr_sequence_length -@item DBR_OUTPUT_SEQEND(@var{file}) +@defmac DBR_OUTPUT_SEQEND (@var{file}) A C statement, to be executed after all slot-filler instructions have been output. If necessary, call @code{dbr_sequence_length} to determine the number of slots filled in a sequence (zero if not @@ -7289,6 +7337,7 @@ or whatever. Don't define this macro if it has nothing to do, but it is helpful in reading assembly output if the extent of the delay sequence is made explicit (e.g.@: with white space). +@end defmac @findex final_sequence Note that output routines for instructions with delay slots must be @@ -7298,36 +7347,32 @@ found.) The variable @code{final_sequence} is null when not processing a sequence, otherwise it contains the @code{sequence} rtx being output. -@findex REGISTER_PREFIX -@findex LOCAL_LABEL_PREFIX -@findex USER_LABEL_PREFIX -@findex IMMEDIATE_PREFIX @findex asm_fprintf -@item REGISTER_PREFIX -@itemx LOCAL_LABEL_PREFIX -@itemx USER_LABEL_PREFIX -@itemx IMMEDIATE_PREFIX +@defmac REGISTER_PREFIX +@defmacx LOCAL_LABEL_PREFIX +@defmacx USER_LABEL_PREFIX +@defmacx IMMEDIATE_PREFIX If defined, C string expressions to be used for the @samp{%R}, @samp{%L}, @samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see @file{final.c}). These are useful when a single @file{md} file must support multiple assembler formats. In that case, the various @file{tm.h} files can define these macros differently. +@end defmac -@item ASM_FPRINTF_EXTENSIONS(@var{file}, @var{argptr}, @var{format}) -@findex ASM_FPRINTF_EXTENSIONS +@defmac ASM_FPRINTF_EXTENSIONS (@var{file}, @var{argptr}, @var{format}) If defined this macro should expand to a series of @code{case} statements which will be parsed inside the @code{switch} statement of the @code{asm_fprintf} function. This allows targets to define extra printf formats which may useful when generating their assembler -statements. Note that upper case letters are reserved for future +statements. Note that uppercase letters are reserved for future generic extensions to asm_fprintf, and so are not available to target specific code. The output file is given by the parameter @var{file}. The varargs input pointer is @var{argptr} and the rest of the format string, starting the character after the one that is being switched upon, is pointed to by @var{format}. +@end defmac -@findex ASSEMBLER_DIALECT -@item ASSEMBLER_DIALECT +@defmac ASSEMBLER_DIALECT If your target supports multiple dialects of assembler language (such as different opcodes), define this macro as a C expression that gives the numeric index of the assembler language dialect to use, with zero as the @@ -7356,21 +7401,21 @@ the variations in assembler language syntax with that mechanism. Define @code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax if the syntax variant are larger and involve such things as different opcodes or operand order. +@end defmac -@findex ASM_OUTPUT_REG_PUSH -@item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) +@defmac ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) A C expression to output to @var{stream} some assembler code which will push hard register number @var{regno} onto the stack. The code need not be optimal, since this macro is used only when profiling. +@end defmac -@findex ASM_OUTPUT_REG_POP -@item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) +@defmac ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) A C expression to output to @var{stream} some assembler code which will pop hard register number @var{regno} off of the stack. The code need not be optimal, since this macro is used only when profiling. -@end table +@end defmac @node Dispatch Tables @subsection Output of Dispatch Tables @@ -7378,48 +7423,46 @@ profiling. @c prevent bad page break with this line This concerns dispatch tables. -@table @code @cindex dispatch table -@findex ASM_OUTPUT_ADDR_DIFF_ELT -@item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) +@defmac ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) A C statement to output to the stdio stream @var{stream} an assembler pseudo-instruction to generate a difference between two labels. @var{value} and @var{rel} are the numbers of two internal labels. The definitions of these labels are output using -@code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same +@code{(*targetm.asm_out.internal_label)}, and they must be printed in the same way here. For example, -@example +@smallexample fprintf (@var{stream}, "\t.word L%d-L%d\n", @var{value}, @var{rel}) -@end example +@end smallexample You must provide this macro on machines where the addresses in a dispatch table are relative to the table's own address. If defined, GCC will also use this macro on all machines when producing PIC@. @var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the mode and flags can be read. +@end defmac -@findex ASM_OUTPUT_ADDR_VEC_ELT -@item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) +@defmac ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) This macro should be provided on machines where the addresses in a dispatch table are absolute. The definition should be a C statement to output to the stdio stream @var{stream} an assembler pseudo-instruction to generate a reference to a label. @var{value} is the number of an internal label whose -definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}. +definition is output using @code{(*targetm.asm_out.internal_label)}. For example, -@example +@smallexample fprintf (@var{stream}, "\t.word L%d\n", @var{value}) -@end example +@end smallexample +@end defmac -@findex ASM_OUTPUT_CASE_LABEL -@item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) +@defmac ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) Define this if the label before a jump-table needs to be output specially. The first three arguments are the same as for -@code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the +@code{(*targetm.asm_out.internal_label)}; the fourth argument is the jump-table which follows (a @code{jump_insn} containing an @code{addr_vec} or @code{addr_diff_vec}). @@ -7427,10 +7470,10 @@ This feature is used on system V to output a @code{swbeg} statement for the table. If this macro is not defined, these labels are output with -@code{ASM_OUTPUT_INTERNAL_LABEL}. +@code{(*targetm.asm_out.internal_label)}. +@end defmac -@findex ASM_OUTPUT_CASE_END -@item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) +@defmac ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) Define this if something special must be output at the end of a jump-table. The definition should be a C statement to be executed after the assembler code for the table is written. It should write @@ -7440,7 +7483,7 @@ of the preceding label. If this macro is not defined, nothing special is output at the end of the jump-table. -@end table +@end defmac @node Exception Region Output @subsection Assembler Commands for Exception Regions @@ -7450,9 +7493,7 @@ the jump-table. This describes commands marking the start and the end of an exception region. -@table @code -@findex EH_FRAME_SECTION_NAME -@item EH_FRAME_SECTION_NAME +@defmac EH_FRAME_SECTION_NAME If defined, a C string constant for the name of the section containing exception handling frame unwind information. If not defined, GCC will provide a default definition if the target supports named sections. @@ -7460,9 +7501,9 @@ provide a default definition if the target supports named sections. You should define this symbol if your target supports DWARF 2 frame unwind information and the default definition does not work. +@end defmac -@findex EH_FRAME_IN_DATA_SECTION -@item EH_FRAME_IN_DATA_SECTION +@defmac EH_FRAME_IN_DATA_SECTION If defined, DWARF 2 frame unwind information will be placed in the data section even though the target supports named sections. This might be necessary, for instance, if the system linker does garbage @@ -7470,14 +7511,14 @@ collection and sections cannot be marked as not to be collected. Do not define this macro unless @code{TARGET_ASM_NAMED_SECTION} is also defined. +@end defmac -@findex MASK_RETURN_ADDR -@item MASK_RETURN_ADDR +@defmac MASK_RETURN_ADDR An rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so that it does not contain any extraneous set bits in it. +@end defmac -@findex DWARF2_UNWIND_INFO -@item DWARF2_UNWIND_INFO +@defmac DWARF2_UNWIND_INFO Define this macro to 0 if your target supports DWARF 2 frame unwind information, but it does not yet work with exception handling. Otherwise, if your target supports this information (if it defines @@ -7491,17 +7532,23 @@ default. If this macro is defined to anything, the DWARF 2 unwinder will be used instead of inline unwinders and @code{__unwind_function} in the non-@code{setjmp} case. +@end defmac + +@defmac MUST_USE_SJLJ_EXCEPTIONS +This macro need only be defined if @code{DWARF2_UNWIND_INFO} is +runtime-variable. In that case, @file{except.h} cannot correctly +determine the corresponding definition of +@code{MUST_USE_SJLJ_EXCEPTIONS}, so the target must provide it directly. +@end defmac -@findex DWARF_CIE_DATA_ALIGNMENT -@item DWARF_CIE_DATA_ALIGNMENT +@defmac DWARF_CIE_DATA_ALIGNMENT This macro need only be defined if the target might save registers in the function prologue at an offset to the stack pointer that is not aligned to @code{UNITS_PER_WORD}. The definition should be the negative minimum alignment if @code{STACK_GROWS_DOWNWARD} is defined, and the positive minimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if the target supports DWARF 2 frame unwind information. - -@end table +@end defmac @deftypefn {Target Hook} void TARGET_ASM_EXCEPTION_SECTION () If defined, a function that switches to the section in which the main @@ -7528,15 +7575,22 @@ Default value is false if @code{EH_FRAME_SECTION_NAME} is defined, and true otherwise. @end deftypevar +@deftypefn {Target Hook} rtx TARGET_DWARF_REGISTER_SPAN (rtx @var{reg}) +Given a register, this hook should return a parallel of registers to +represent where to find the register pieces. Define this hook if the +register and its mode are represented in Dwarf in non-contiguous +locations, or if the register should be represented in more than one +register in Dwarf. Otherwise, this hook should return @code{NULL_RTX}. +If not defined, the default is to return @code{NULL_RTX}. +@end deftypefn + @node Alignment Output @subsection Assembler Commands for Alignment @c prevent bad page break with this line This describes commands for alignment. -@table @code -@findex JUMP_ALIGN -@item JUMP_ALIGN (@var{label}) +@defmac JUMP_ALIGN (@var{label}) The alignment (log base 2) to put in front of @var{label}, which is a common destination of jumps and has no fallthru incoming edge. @@ -7548,24 +7602,24 @@ Unless it's necessary to inspect the @var{label} parameter, it is better to set the variable @var{align_jumps} in the target's @code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's selection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation. +@end defmac -@findex LABEL_ALIGN_AFTER_BARRIER -@item LABEL_ALIGN_AFTER_BARRIER (@var{label}) +@defmac LABEL_ALIGN_AFTER_BARRIER (@var{label}) The alignment (log base 2) to put in front of @var{label}, which follows a @code{BARRIER}. This macro need not be defined if you don't want any special alignment to be done at such a time. Most machine descriptions do not currently define the macro. +@end defmac -@findex LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP -@item LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP +@defmac LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP The maximum number of bytes to skip when applying @code{LABEL_ALIGN_AFTER_BARRIER}. This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. +@end defmac -@findex LOOP_ALIGN -@item LOOP_ALIGN (@var{label}) +@defmac LOOP_ALIGN (@var{label}) The alignment (log base 2) to put in front of @var{label}, which follows a @code{NOTE_INSN_LOOP_BEG} note. @@ -7577,14 +7631,14 @@ Unless it's necessary to inspect the @var{label} parameter, it is better to set the variable @code{align_loops} in the target's @code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. +@end defmac -@findex LOOP_ALIGN_MAX_SKIP -@item LOOP_ALIGN_MAX_SKIP +@defmac LOOP_ALIGN_MAX_SKIP The maximum number of bytes to skip when applying @code{LOOP_ALIGN}. This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. +@end defmac -@findex LABEL_ALIGN -@item LABEL_ALIGN (@var{label}) +@defmac LABEL_ALIGN (@var{label}) The alignment (log base 2) to put in front of @var{label}. If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, the maximum of the specified values is used. @@ -7593,46 +7647,46 @@ Unless it's necessary to inspect the @var{label} parameter, it is better to set the variable @code{align_labels} in the target's @code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. +@end defmac -@findex LABEL_ALIGN_MAX_SKIP -@item LABEL_ALIGN_MAX_SKIP +@defmac LABEL_ALIGN_MAX_SKIP The maximum number of bytes to skip when applying @code{LABEL_ALIGN}. This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. +@end defmac -@findex ASM_OUTPUT_SKIP -@item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) +@defmac ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) A C statement to output to the stdio stream @var{stream} an assembler instruction to advance the location counter by @var{nbytes} bytes. Those bytes should be zero when loaded. @var{nbytes} will be a C expression of type @code{int}. +@end defmac -@findex ASM_NO_SKIP_IN_TEXT -@item ASM_NO_SKIP_IN_TEXT +@defmac ASM_NO_SKIP_IN_TEXT Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the text section because it fails to put zeros in the bytes that are skipped. This is true on many Unix systems, where the pseudo--op to skip bytes produces no-op instructions rather than zeros when used in the text section. +@end defmac -@findex ASM_OUTPUT_ALIGN -@item ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) +@defmac ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) A C statement to output to the stdio stream @var{stream} an assembler command to advance the location counter to a multiple of 2 to the @var{power} bytes. @var{power} will be a C expression of type @code{int}. +@end defmac -@findex ASM_OUTPUT_ALIGN_WITH_NOP -@item ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power}) +@defmac ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power}) Like @code{ASM_OUTPUT_ALIGN}, except that the ``nop'' instruction is used for padding, if necessary. +@end defmac -@findex ASM_OUTPUT_MAX_SKIP_ALIGN -@item ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) +@defmac ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) A C statement to output to the stdio stream @var{stream} an assembler command to advance the location counter to a multiple of 2 to the @var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to satisfy the alignment request. @var{power} and @var{max_skip} will be a C expression of type @code{int}. -@end table +@end defmac @need 3000 @node Debugging Info @@ -7656,9 +7710,7 @@ This describes how to specify debugging information. @c prevent bad page break with this line These macros affect all debugging formats. -@table @code -@findex DBX_REGISTER_NUMBER -@item DBX_REGISTER_NUMBER (@var{regno}) +@defmac DBX_REGISTER_NUMBER (@var{regno}) A C expression that returns the DBX register number for the compiler register number @var{regno}. In the default macro provided, the value of this expression will be @var{regno} itself. But sometimes there are @@ -7675,9 +7727,9 @@ expect register pairs to be consecutive in their own numbering scheme. If you find yourself defining @code{DBX_REGISTER_NUMBER} in way that does not preserve register pairs, then what you must do instead is redefine the actual register numbering scheme. +@end defmac -@findex DEBUGGER_AUTO_OFFSET -@item DEBUGGER_AUTO_OFFSET (@var{x}) +@defmac DEBUGGER_AUTO_OFFSET (@var{x}) A C expression that returns the integer offset value for an automatic variable having address @var{x} (an RTL expression). The default computation assumes that @var{x} is based on the frame-pointer and @@ -7685,15 +7737,15 @@ gives the offset from the frame-pointer. This is required for targets that produce debugging output for DBX or COFF-style debugging output for SDB and allow the frame-pointer to be eliminated when the @option{-g} options is used. +@end defmac -@findex DEBUGGER_ARG_OFFSET -@item DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) +@defmac DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) A C expression that returns the integer offset value for an argument having address @var{x} (an RTL expression). The nominal offset is @var{offset}. +@end defmac -@findex PREFERRED_DEBUGGING_TYPE -@item PREFERRED_DEBUGGING_TYPE +@defmac PREFERRED_DEBUGGING_TYPE A C expression that returns the type of debugging output GCC should produce when the user specifies just @option{-g}. Define this if you have arranged for GCC to support more than one format of @@ -7703,16 +7755,14 @@ debugging output. Currently, the allowable values are @code{DBX_DEBUG}, When the user specifies @option{-ggdb}, GCC normally also uses the value of this macro to select the debugging output format, but with two -exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined and -@code{LINKER_DOES_NOT_WORK_WITH_DWARF2} is not defined, GCC uses the +exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined, GCC uses the value @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is defined, GCC uses @code{DBX_DEBUG}. The value of this macro only affects the default debugging output; the user can always get a specific type of output by using @option{-gstabs}, -@option{-gcoff}, @option{-gdwarf-1}, @option{-gdwarf-2}, @option{-gxcoff}, -or @option{-gvms}. -@end table +@option{-gcoff}, @option{-gdwarf-2}, @option{-gxcoff}, or @option{-gvms}. +@end defmac @node DBX Options @subsection Specific Options for DBX Output @@ -7720,61 +7770,59 @@ or @option{-gvms}. @c prevent bad page break with this line These are specific options for DBX output. -@table @code -@findex DBX_DEBUGGING_INFO -@item DBX_DEBUGGING_INFO +@defmac DBX_DEBUGGING_INFO Define this macro if GCC should produce debugging output for DBX in response to the @option{-g} option. +@end defmac -@findex XCOFF_DEBUGGING_INFO -@item XCOFF_DEBUGGING_INFO +@defmac XCOFF_DEBUGGING_INFO Define this macro if GCC should produce XCOFF format debugging output in response to the @option{-g} option. This is a variant of DBX format. +@end defmac -@findex DEFAULT_GDB_EXTENSIONS -@item DEFAULT_GDB_EXTENSIONS +@defmac DEFAULT_GDB_EXTENSIONS Define this macro to control whether GCC should by default generate GDB's extended version of DBX debugging information (assuming DBX-format debugging information is enabled at all). If you don't define the macro, the default is 1: always generate the extended information if there is any occasion to. +@end defmac -@findex DEBUG_SYMS_TEXT -@item DEBUG_SYMS_TEXT +@defmac DEBUG_SYMS_TEXT Define this macro if all @code{.stabs} commands should be output while in the text section. +@end defmac -@findex ASM_STABS_OP -@item ASM_STABS_OP +@defmac ASM_STABS_OP A C string constant, including spacing, naming the assembler pseudo op to use instead of @code{"\t.stabs\t"} to define an ordinary debugging symbol. If you don't define this macro, @code{"\t.stabs\t"} is used. This macro applies only to DBX debugging information format. +@end defmac -@findex ASM_STABD_OP -@item ASM_STABD_OP +@defmac ASM_STABD_OP A C string constant, including spacing, naming the assembler pseudo op to use instead of @code{"\t.stabd\t"} to define a debugging symbol whose value is the current location. If you don't define this macro, @code{"\t.stabd\t"} is used. This macro applies only to DBX debugging information format. +@end defmac -@findex ASM_STABN_OP -@item ASM_STABN_OP +@defmac ASM_STABN_OP A C string constant, including spacing, naming the assembler pseudo op to use instead of @code{"\t.stabn\t"} to define a debugging symbol with no name. If you don't define this macro, @code{"\t.stabn\t"} is used. This macro applies only to DBX debugging information format. +@end defmac -@findex DBX_NO_XREFS -@item DBX_NO_XREFS +@defmac DBX_NO_XREFS Define this macro if DBX on your system does not support the construct @samp{xs@var{tagname}}. On some systems, this construct is used to describe a forward reference to a structure named @var{tagname}. On other systems, this construct is not supported at all. +@end defmac -@findex DBX_CONTIN_LENGTH -@item DBX_CONTIN_LENGTH +@defmac DBX_CONTIN_LENGTH A symbol name in DBX-format debugging information is normally continued (split into two separate @code{.stabs} directives) when it exceeds a certain length (by default, 80 characters). On some @@ -7782,78 +7830,71 @@ operating systems, DBX requires this splitting; on others, splitting must not be done. You can inhibit splitting by defining this macro with the value zero. You can override the default splitting-length by defining this macro as an expression for the length you desire. +@end defmac -@findex DBX_CONTIN_CHAR -@item DBX_CONTIN_CHAR +@defmac DBX_CONTIN_CHAR Normally continuation is indicated by adding a @samp{\} character to the end of a @code{.stabs} string when a continuation follows. To use a different character instead, define this macro as a character constant for the character you want to use. Do not define this macro if backslash is correct for your system. +@end defmac -@findex DBX_STATIC_STAB_DATA_SECTION -@item DBX_STATIC_STAB_DATA_SECTION +@defmac DBX_STATIC_STAB_DATA_SECTION Define this macro if it is necessary to go to the data section before outputting the @samp{.stabs} pseudo-op for a non-global static variable. +@end defmac -@findex DBX_TYPE_DECL_STABS_CODE -@item DBX_TYPE_DECL_STABS_CODE +@defmac DBX_TYPE_DECL_STABS_CODE The value to use in the ``code'' field of the @code{.stabs} directive for a typedef. The default is @code{N_LSYM}. +@end defmac -@findex DBX_STATIC_CONST_VAR_CODE -@item DBX_STATIC_CONST_VAR_CODE +@defmac DBX_STATIC_CONST_VAR_CODE The value to use in the ``code'' field of the @code{.stabs} directive for a static variable located in the text section. DBX format does not provide any ``right'' way to do this. The default is @code{N_FUN}. +@end defmac -@findex DBX_REGPARM_STABS_CODE -@item DBX_REGPARM_STABS_CODE +@defmac DBX_REGPARM_STABS_CODE The value to use in the ``code'' field of the @code{.stabs} directive for a parameter passed in registers. DBX format does not provide any ``right'' way to do this. The default is @code{N_RSYM}. +@end defmac -@findex DBX_REGPARM_STABS_LETTER -@item DBX_REGPARM_STABS_LETTER +@defmac DBX_REGPARM_STABS_LETTER The letter to use in DBX symbol data to identify a symbol as a parameter passed in registers. DBX format does not customarily provide any way to do this. The default is @code{'P'}. +@end defmac -@findex DBX_MEMPARM_STABS_LETTER -@item DBX_MEMPARM_STABS_LETTER +@defmac DBX_MEMPARM_STABS_LETTER The letter to use in DBX symbol data to identify a symbol as a stack parameter. The default is @code{'p'}. +@end defmac -@findex DBX_FUNCTION_FIRST -@item DBX_FUNCTION_FIRST +@defmac DBX_FUNCTION_FIRST Define this macro if the DBX information for a function and its arguments should precede the assembler code for the function. Normally, in DBX format, the debugging information entirely follows the assembler code. +@end defmac -@findex DBX_LBRAC_FIRST -@item DBX_LBRAC_FIRST -Define this macro if the @code{N_LBRAC} symbol for a block should -precede the debugging information for variables and functions defined in -that block. Normally, in DBX format, the @code{N_LBRAC} symbol comes -first. - -@findex DBX_BLOCKS_FUNCTION_RELATIVE -@item DBX_BLOCKS_FUNCTION_RELATIVE +@defmac DBX_BLOCKS_FUNCTION_RELATIVE Define this macro if the value of a symbol describing the scope of a block (@code{N_LBRAC} or @code{N_RBRAC}) should be relative to the start of the enclosing function. Normally, GCC uses an absolute address. +@end defmac -@findex DBX_USE_BINCL -@item DBX_USE_BINCL +@defmac DBX_USE_BINCL Define this macro if GCC should generate @code{N_BINCL} and @code{N_EINCL} stabs for included header files, as on Sun systems. This macro also directs GCC to output a type number as a pair of a file number and a type number within the file. Normally, GCC does not generate @code{N_BINCL} or @code{N_EINCL} stabs, and it outputs a single number for a type number. -@end table +@end defmac @node DBX Hooks @subsection Open-Ended Hooks for DBX Format @@ -7861,40 +7902,31 @@ number for a type number. @c prevent bad page break with this line These are hooks for DBX format. -@table @code -@findex DBX_OUTPUT_LBRAC -@item DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) +@defmac DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) Define this macro to say how to output to @var{stream} the debugging information for the start of a scope level for variable names. The argument @var{name} is the name of an assembler symbol (for use with @code{assemble_name}) whose value is the address where the scope begins. +@end defmac -@findex DBX_OUTPUT_RBRAC -@item DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) +@defmac DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. +@end defmac -@findex DBX_OUTPUT_NFUN -@item DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl}) +@defmac 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}. +@end defmac -@findex DBX_OUTPUT_ENUM -@item DBX_OUTPUT_ENUM (@var{stream}, @var{type}) -Define this macro if the target machine requires special handling to -output an enumeration type. The definition should be a C statement -(sans semicolon) to output the appropriate information to @var{stream} -for the type @var{type}. - -@findex DBX_OUTPUT_FUNCTION_END -@item DBX_OUTPUT_FUNCTION_END (@var{stream}, @var{function}) +@defmac DBX_OUTPUT_FUNCTION_END (@var{stream}, @var{function}) Define this macro if the target machine requires special output at the end of the debugging information for a function. The definition should be a C statement (sans semicolon) to output the appropriate information to @var{stream}. @var{function} is the @code{FUNCTION_DECL} node for the function. +@end defmac -@findex DBX_OUTPUT_STANDARD_TYPES -@item DBX_OUTPUT_STANDARD_TYPES (@var{syms}) +@defmac DBX_OUTPUT_STANDARD_TYPES (@var{syms}) Define this macro if you need to control the order of output of the standard data types at the beginning of compilation. The argument @var{syms} is a @code{tree} which is a chain of all the predefined @@ -7951,15 +7983,14 @@ Here is another way of finding a particular type: @} @end group @end smallexample +@end defmac -@findex NO_DBX_FUNCTION_END -@item NO_DBX_FUNCTION_END +@defmac NO_DBX_FUNCTION_END Some stabs encapsulation formats (in particular ECOFF), cannot handle the @code{.stabs "",N_FUN,,0,0,Lscope-function-1} gdb dbx extension construct. On those machines, define this macro to turn this feature off without disturbing the rest of the gdb extensions. - -@end table +@end defmac @node File Names and DBX @subsection File Names in DBX Format @@ -7967,17 +7998,7 @@ disturbing the rest of the gdb extensions. @c prevent bad page break with this line This describes file names in DBX format. -@table @code -@findex DBX_WORKING_DIRECTORY -@item DBX_WORKING_DIRECTORY -Define this if DBX wants to have the current directory recorded in each -object file. - -Note that the working directory is always recorded if GDB extensions are -enabled. - -@findex DBX_OUTPUT_MAIN_SOURCE_FILENAME -@item DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) +@defmac DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) A C statement to output DBX debugging information to the stdio stream @var{stream} which indicates that file @var{name} is the main source file---the file specified as the input file for compilation. @@ -7985,35 +8006,24 @@ This macro is called only once, at the beginning of compilation. This macro need not be defined if the standard form of output for DBX debugging information is appropriate. +@end defmac -@findex DBX_OUTPUT_MAIN_SOURCE_DIRECTORY -@item DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (@var{stream}, @var{name}) +@defmac DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (@var{stream}, @var{name}) A C statement to output DBX debugging information to the stdio stream @var{stream} which indicates that the current directory during compilation is named @var{name}. This macro need not be defined if the standard form of output for DBX debugging information is appropriate. +@end defmac -@findex DBX_OUTPUT_MAIN_SOURCE_FILE_END -@item DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) +@defmac DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) A C statement to output DBX debugging information at the end of compilation of the main source file @var{name}. If you don't define this macro, nothing special is output at the end of compilation, which is correct for most machines. - -@findex DBX_OUTPUT_SOURCE_FILENAME -@item DBX_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) -A C statement to output DBX debugging information to the stdio stream -@var{stream} which indicates that file @var{name} is the current source -file. This output is generated each time input shifts to a different -source file as a result of @samp{#include}, the end of an included file, -or a @samp{#line} command. - -This macro need not be defined if the standard form of output -for DBX debugging information is appropriate. -@end table +@end defmac @need 2000 @node SDB and DWARF @@ -8022,19 +8032,12 @@ for DBX debugging information is appropriate. @c prevent bad page break with this line Here are macros for SDB and DWARF output. -@table @code -@findex SDB_DEBUGGING_INFO -@item SDB_DEBUGGING_INFO +@defmac SDB_DEBUGGING_INFO Define this macro if GCC should produce COFF-style debugging output for SDB in response to the @option{-g} option. +@end defmac -@findex DWARF_DEBUGGING_INFO -@item DWARF_DEBUGGING_INFO -Define this macro if GCC should produce dwarf format debugging output -in response to the @option{-g} option. - -@findex DWARF2_DEBUGGING_INFO -@item DWARF2_DEBUGGING_INFO +@defmac DWARF2_DEBUGGING_INFO Define this macro if GCC should produce dwarf version 2 format debugging output in response to the @option{-g} option. @@ -8043,84 +8046,77 @@ define @code{INCOMING_RETURN_ADDR_RTX} and either set @code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the prologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save} as appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't. +@end defmac -@findex DWARF2_FRAME_INFO -@item DWARF2_FRAME_INFO +@defmac DWARF2_FRAME_INFO Define this macro to a nonzero value if GCC should always output Dwarf 2 frame information. If @code{DWARF2_UNWIND_INFO} (@pxref{Exception Region Output} is nonzero, GCC will output this information not matter how you define @code{DWARF2_FRAME_INFO}. +@end defmac -@findex LINKER_DOES_NOT_WORK_WITH_DWARF2 -@item LINKER_DOES_NOT_WORK_WITH_DWARF2 -Define this macro if the linker does not work with Dwarf version 2. -Normally, if the user specifies only @option{-ggdb} GCC will use Dwarf -version 2 if available; this macro disables this. See the description -of the @code{PREFERRED_DEBUGGING_TYPE} macro for more details. - -@findex DWARF2_GENERATE_TEXT_SECTION_LABEL -@item DWARF2_GENERATE_TEXT_SECTION_LABEL +@defmac DWARF2_GENERATE_TEXT_SECTION_LABEL By default, the Dwarf 2 debugging information generator will generate a label to mark the beginning of the text section. If it is better simply to use the name of the text section itself, rather than an explicit label, to indicate the beginning of the text section, define this macro to zero. +@end defmac -@findex DWARF2_ASM_LINE_DEBUG_INFO -@item DWARF2_ASM_LINE_DEBUG_INFO +@defmac DWARF2_ASM_LINE_DEBUG_INFO Define this macro to be a nonzero value if the assembler can generate Dwarf 2 line debug info sections. This will result in much more compact line number tables, and hence is desirable if it works. +@end defmac -@findex ASM_OUTPUT_DWARF_DELTA -@item ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) +@defmac ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) A C statement to issue assembly directives that create a difference between the two given labels, using an integer of the given size. +@end defmac -@findex ASM_OUTPUT_DWARF_OFFSET -@item ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}) +@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}) A C statement to issue assembly directives that create a section-relative reference to the given label, using an integer of the given size. +@end defmac -@findex ASM_OUTPUT_DWARF_PCREL -@item ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) +@defmac ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) A C statement to issue assembly directives that create a self-relative reference to the given label, using an integer of the given size. +@end defmac -@findex PUT_SDB_@dots{} -@item PUT_SDB_@dots{} +@defmac PUT_SDB_@dots{} Define these macros to override the assembler syntax for the special SDB assembler directives. See @file{sdbout.c} for a list of these macros and their arguments. If the standard syntax is used, you need not define them yourself. +@end defmac -@findex SDB_DELIM -@item SDB_DELIM +@defmac SDB_DELIM Some assemblers do not support a semicolon as a delimiter, even between SDB assembler directives. In that case, define this macro to be the delimiter to use (usually @samp{\n}). It is not necessary to define a new set of @code{PUT_SDB_@var{op}} macros if this is the only change required. +@end defmac -@findex SDB_GENERATE_FAKE -@item SDB_GENERATE_FAKE +@defmac SDB_GENERATE_FAKE Define this macro to override the usual method of constructing a dummy name for anonymous structure and union types. See @file{sdbout.c} for more information. +@end defmac -@findex SDB_ALLOW_UNKNOWN_REFERENCES -@item SDB_ALLOW_UNKNOWN_REFERENCES +@defmac SDB_ALLOW_UNKNOWN_REFERENCES Define this macro to allow references to unknown structure, union, or enumeration tags to be emitted. Standard COFF does not allow handling of unknown references, MIPS ECOFF has support for it. +@end defmac -@findex SDB_ALLOW_FORWARD_REFERENCES -@item SDB_ALLOW_FORWARD_REFERENCES +@defmac SDB_ALLOW_FORWARD_REFERENCES Define this macro to allow references to structure, union, or enumeration tags that have not yet been seen to be handled. Some assemblers choke if forward tags are used, while some require it. -@end table +@end defmac @need 2000 @node VMS Debug @@ -8129,16 +8125,14 @@ assemblers choke if forward tags are used, while some require it. @c prevent bad page break with this line Here are macros for VMS debug format. -@table @code -@findex VMS_DEBUGGING_INFO -@item VMS_DEBUGGING_INFO +@defmac VMS_DEBUGGING_INFO Define this macro if GCC should produce debugging output for VMS in response to the @option{-g} option. The default behavior for VMS is to generate minimal debug info for a traceback in the absence of @option{-g} unless explicitly overridden with @option{-g0}. This behavior is controlled by @code{OPTIMIZATION_OPTIONS} and @code{OVERRIDE_OPTIONS}. -@end table +@end defmac @node Floating Point @section Cross Compilation and Floating Point @@ -8247,7 +8241,6 @@ integral, it is truncated. @end deftypefn @deftypefn Macro void REAL_VALUE_FROM_INT (REAL_VALUE_TYPE @var{x}, HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, enum machine_mode @var{mode}) -@findex REAL_VALUE_FROM_INT Converts a double-precision integer found in @var{low} and @var{high}, into a floating point value which is then stored into @var{x}. The value is truncated to fit in mode @var{mode}. @@ -8258,9 +8251,7 @@ value is truncated to fit in mode @var{mode}. @cindex mode switching The following macros control mode switching optimizations: -@table @code -@findex OPTIMIZE_MODE_SWITCHING -@item OPTIMIZE_MODE_SWITCHING (@var{entity}) +@defmac OPTIMIZE_MODE_SWITCHING (@var{entity}) Define this macro if the port needs extra instructions inserted for mode switching in an optimizing compilation. @@ -8270,7 +8261,7 @@ the FPSCR PR bit has to be cleared, while for a double precision operation, this bit has to be set. Changing the PR bit requires a general purpose register as a scratch register, hence these FPSCR sets have to be inserted before reload, i.e.@: you can't put this into instruction emitting -or @code{MACHINE_DEPENDENT_REORG}. +or @code{TARGET_MACHINE_DEPENDENT_REORG}. You can have multiple entities that are mode-switched, and select at run time which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should @@ -8278,10 +8269,11 @@ return nonzero for any @var{entity} that needs mode-switching. If you define this macro, you also have to define @code{NUM_MODES_FOR_MODE_SWITCHING}, @code{MODE_NEEDED}, @code{MODE_PRIORITY_TO_MODE} and @code{EMIT_MODE_SET}. -@code{NORMAL_MODE} is optional. +@code{MODE_AFTER}, @code{MODE_ENTRY}, and @code{MODE_EXIT} +are optional. +@end defmac -@findex NUM_MODES_FOR_MODE_SWITCHING -@item NUM_MODES_FOR_MODE_SWITCHING +@defmac NUM_MODES_FOR_MODE_SWITCHING If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as initializer for an array of integers. Each initializer element N refers to an entity that needs mode switching, and specifies the number @@ -8292,36 +8284,50 @@ entity in question. In macros that take mode arguments / yield a mode result, modes are represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode switch is needed / supplied. +@end defmac -@findex MODE_NEEDED -@item MODE_NEEDED (@var{entity}, @var{insn}) +@defmac MODE_NEEDED (@var{entity}, @var{insn}) @var{entity} is an integer specifying a mode-switched entity. If @code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to return an integer value not larger than the corresponding element in @code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must be switched into prior to the execution of @var{insn}. +@end defmac + +@defmac MODE_AFTER (@var{mode}, @var{insn}) +If this macro is defined, it is evaluated for every @var{insn} during +mode switching. It determines the mode that an insn results in (if +different from the incoming mode). +@end defmac + +@defmac MODE_ENTRY (@var{entity}) +If this macro is defined, it is evaluated for every @var{entity} that needs +mode switching. It should evaluate to an integer, which is a mode that +@var{entity} is assumed to be switched to at function entry. If @code{MODE_ENTRY} +is defined then @code{MODE_EXIT} must be defined. +@end defmac -@findex NORMAL_MODE -@item NORMAL_MODE (@var{entity}) +@defmac MODE_EXIT (@var{entity}) If this macro is defined, it is evaluated for every @var{entity} that needs -mode switching. It should evaluate to an integer, which is a mode that -@var{entity} is assumed to be switched to at function entry and exit. +mode switching. It should evaluate to an integer, which is a mode that +@var{entity} is assumed to be switched to at function exit. If @code{MODE_EXIT} +is defined then @code{MODE_ENTRY} must be defined. +@end defmac -@findex MODE_PRIORITY_TO_MODE -@item MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) +@defmac MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) This macro specifies the order in which modes for @var{entity} are processed. 0 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the lowest. The value of the macro should be an integer designating a mode for @var{entity}. For any fixed @var{entity}, @code{mode_priority_to_mode} (@var{entity}, @var{n}) shall be a bijection in 0 @dots{} @code{num_modes_for_mode_switching[@var{entity}] - 1}. +@end defmac -@findex EMIT_MODE_SET -@item EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) +@defmac EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) Generate one or more insns to set @var{entity} to @var{mode}. @var{hard_reg_live} is the set of hard registers live at the point where the insn(s) are to be inserted. -@end table +@end defmac @node Target Attributes @section Defining target-specific uses of @code{__attribute__} @@ -8374,7 +8380,7 @@ call @code{merge_attributes} to handle machine-independent merging. @findex TARGET_DLLIMPORT_DECL_ATTRIBUTES If the only target-specific handling you require is @samp{dllimport} for -Windows targets, you should define the macro +Microsoft Windows targets, you should define the macro @code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. This links in a function called @code{merge_dllimport_decl_attributes} which can then be defined as the expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. This is done @@ -8407,7 +8413,7 @@ target specific attribute attached to it, it will not be inlined. @cindex MIPS coprocessor-definition macros The MIPS specification allows MIPS implementations to have as many as 4 -coprocessors, each with as many as 32 private registers. gcc supports +coprocessors, each with as many as 32 private registers. GCC supports accessing these registers and transferring values between the registers and memory using asm-ized variables. For example: @@ -8433,18 +8439,38 @@ floating-point support; they are not included in this mechanism. There is one macro used in defining the MIPS coprocessor interface which you may want to override in subtargets; it is described below. -@table @code - -@item ALL_COP_ADDITIONAL_REGISTER_NAMES -@findex ALL_COP_ADDITIONAL_REGISTER_NAMES +@defmac ALL_COP_ADDITIONAL_REGISTER_NAMES A comma-separated list (with leading comma) of pairs describing the alternate names of coprocessor registers. The format of each entry should be @smallexample @{ @var{alternatename}, @var{register_number}@} @end smallexample Default: empty. +@end defmac + +@node PCH Target +@section Parameters for Precompiled Header Validity Checking +@cindex parameters, precompiled headers + +@deftypefn {Target Hook} void * TARGET_GET_PCH_VALIDITY (size_t * @var{sz}) +Define this hook if your target needs to check a different collection +of flags than the default, which is every flag defined by +@code{TARGET_SWITCHES} and @code{TARGET_OPTIONS}. It should return +some data which will be saved in the PCH file and presented to +@code{TARGET_PCH_VALID_P} later; it should set @code{SZ} to the size +of the data. +@end deftypefn -@end table +@deftypefn {Target Hook} const char * TARGET_PCH_VALID_P (const void * @var{data}, size_t @var{sz}) +Define this hook if your target needs to check a different collection of +flags than the default, which is every flag defined by @code{TARGET_SWITCHES} +and @code{TARGET_OPTIONS}. It is given data which came from +@code{TARGET_GET_PCH_VALIDITY} (in this version of this compiler, so there +is no need for extensive validity checking). It returns @code{NULL} if +it is safe to load a PCH file with this data, or a suitable error message +if not. The error message will be presented to the user, so it should +be localized. +@end deftypefn @node Misc @section Miscellaneous Parameters @@ -8453,9 +8479,7 @@ Default: empty. @c prevent bad page break with this line Here are several miscellaneous parameters. -@table @code -@item PREDICATE_CODES -@findex PREDICATE_CODES +@defmac PREDICATE_CODES Define this if you have defined special-purpose predicates in the file @file{@var{machine}.c}. This macro is called within an initializer of an array of structures. The first field in the structure is the name of a @@ -8480,9 +8504,9 @@ patterns. For each predicate function named in @code{PREDICATE_CODES}, a declaration will be generated in @file{insn-codes.h}. +@end defmac -@item SPECIAL_MODE_PREDICATES -@findex SPECIAL_MODE_PREDICATES +@defmac SPECIAL_MODE_PREDICATES Define this if you have special predicates that know special things about modes. Genrecog will warn about certain forms of @code{match_operand} without a mode; if the operand predicate is @@ -8497,14 +8521,14 @@ for a byte extraction from @code{%ah} etc.). #define SPECIAL_MODE_PREDICATES \ "ext_register_operand", @end smallexample +@end defmac -@findex CASE_VECTOR_MODE -@item CASE_VECTOR_MODE +@defmac CASE_VECTOR_MODE An alias for a machine mode name. This is the machine mode that elements of a jump-table should have. +@end defmac -@findex CASE_VECTOR_SHORTEN_MODE -@item CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) +@defmac CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) Optional: return the preferred mode for an @code{addr_diff_vec} when the minimum and maximum offset are known. If you define this, it enables extra code in branch shortening to deal with @code{addr_diff_vec}. @@ -8512,74 +8536,97 @@ To make this work, you also have to define @code{INSN_ALIGN} and make the alignment for @code{addr_diff_vec} explicit. The @var{body} argument is provided so that the offset_unsigned and scale flags can be updated. +@end defmac -@findex CASE_VECTOR_PC_RELATIVE -@item CASE_VECTOR_PC_RELATIVE +@defmac CASE_VECTOR_PC_RELATIVE Define this macro to be a C expression to indicate when jump-tables -should contain relative addresses. If jump-tables never contain -relative addresses, then you need not define this macro. +should contain relative addresses. You need not define this macro if +jump-tables never contain relative addresses, or jump-tables should +contain relative addresses only when @option{-fPIC} or @option{-fPIC} +is in effect. +@end defmac -@findex CASE_DROPS_THROUGH -@item CASE_DROPS_THROUGH +@defmac CASE_DROPS_THROUGH Define this if control falls through a @code{case} insn when the index value is out of range. This means the specified default-label is actually ignored by the @code{case} insn proper. +@end defmac -@findex CASE_VALUES_THRESHOLD -@item CASE_VALUES_THRESHOLD +@defmac CASE_VALUES_THRESHOLD Define this to be the smallest number of different values for which it is best to use a jump-table instead of a tree of conditional branches. The default is four for machines with a @code{casesi} instruction and five otherwise. This is best for most machines. +@end defmac + +@defmac CASE_USE_BIT_TESTS +Define this macro to be a C expression to indicate whether C switch +statements may be implemented by a sequence of bit tests. This is +advantageous on processors that can efficiently implement left shift +of 1 by the number of bits held in a register, but inappropriate on +targets that would require a loop. By default, this macro returns +@code{true} if the target defines an @code{ashlsi3} pattern, and +@code{false} otherwise. +@end defmac -@findex WORD_REGISTER_OPERATIONS -@item WORD_REGISTER_OPERATIONS +@defmac WORD_REGISTER_OPERATIONS Define this macro if operations between registers with integral mode smaller than a word are always performed on the entire register. Most RISC machines have this property and most CISC machines do not. +@end defmac -@findex LOAD_EXTEND_OP -@item LOAD_EXTEND_OP (@var{mode}) +@defmac LOAD_EXTEND_OP (@var{mem_mode}) Define this macro to be a C expression indicating when insns that read -memory in @var{mode}, an integral mode narrower than a word, set the -bits outside of @var{mode} to be either the sign-extension or the +memory in @var{mem_mode}, an integral mode narrower than a word, set the +bits outside of @var{mem_mode} to be either the sign-extension or the zero-extension of the data read. Return @code{SIGN_EXTEND} for values -of @var{mode} for which the +of @var{mem_mode} for which the insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and @code{NIL} for other modes. -This macro is not called with @var{mode} non-integral or with a width +This macro is not called with @var{mem_mode} non-integral or with a width greater than or equal to @code{BITS_PER_WORD}, so you may return any value in this case. Do not define this macro if it would always return @code{NIL}. On machines where this macro is defined, you will normally define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. -@findex SHORT_IMMEDIATES_SIGN_EXTEND -@item SHORT_IMMEDIATES_SIGN_EXTEND +You may return a non-@code{NIL} value even if for some hard registers +the sign extension is not performed, if for the @code{REGNO_REG_CLASS} +of these hard registers @code{CANNOT_CHANGE_MODE_CLASS} returns nonzero +when the @var{from} mode is @var{mem_mode} and the @var{to} mode is any +integral mode larger than this but not larger than @code{word_mode}. + +You must return @code{NIL} if for some hard registers that allow this +mode, @code{CANNOT_CHANGE_MODE_CLASS} says that they cannot change to +@code{word_mode}, but that they can change to another integral mode that +is larger then @var{mem_mode} but still smaller than @code{word_mode}. +@end defmac + +@defmac SHORT_IMMEDIATES_SIGN_EXTEND Define this macro if loading short immediate values into registers sign extends. +@end defmac -@findex FIXUNS_TRUNC_LIKE_FIX_TRUNC -@item FIXUNS_TRUNC_LIKE_FIX_TRUNC +@defmac FIXUNS_TRUNC_LIKE_FIX_TRUNC Define this macro if the same instructions that convert a floating point number to a signed fixed point number also convert validly to an unsigned one. +@end defmac -@findex MOVE_MAX -@item MOVE_MAX +@defmac MOVE_MAX The maximum number of bytes that a single instruction can move quickly between memory and registers or between two memory locations. +@end defmac -@findex MAX_MOVE_MAX -@item MAX_MOVE_MAX +@defmac MAX_MOVE_MAX The maximum number of bytes that a single instruction can move quickly between memory and registers or between two memory locations. If this is undefined, the default is @code{MOVE_MAX}. Otherwise, it is the constant value that is the largest value that @code{MOVE_MAX} can have at run-time. +@end defmac -@findex SHIFT_COUNT_TRUNCATED -@item SHIFT_COUNT_TRUNCATED +@defmac SHIFT_COUNT_TRUNCATED A C expression that is nonzero if on this machine the number of bits actually used for the count of a shift operation is equal to the number of bits needed to represent the size of the object being shifted. When @@ -8602,9 +8649,9 @@ such machines. Instead, add patterns to the @file{md} file that include the implied truncation of the shift instructions. You need not define this macro if it would always have the value of zero. +@end defmac -@findex TRULY_NOOP_TRUNCATION -@item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) +@defmac TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) A C expression which is nonzero if on this machine it is safe to ``convert'' an integer of @var{inprec} bits to one of @var{outprec} bits (where @var{outprec} is smaller than @var{inprec}) by merely @@ -8618,9 +8665,9 @@ When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in such cases may improve things. +@end defmac -@findex STORE_FLAG_VALUE -@item STORE_FLAG_VALUE +@defmac STORE_FLAG_VALUE A C expression describing the value returned by a comparison operator with an integral mode and stored by a store-flag instruction (@samp{s@var{cond}}) when the condition is true. This description must @@ -8713,19 +8760,38 @@ and @code{decscc}, respectively, for the patterns which perform @file{rs6000.md} for some examples. The GNU Superoptizer can be used to find such instruction sequences on other machines. -You need not define @code{STORE_FLAG_VALUE} if the machine has no store-flag -instructions. +If this macro is not defined, the default value, 1, is used. You need +not define @code{STORE_FLAG_VALUE} if the machine has no store-flag +instructions, or if the value generated by these instructions is 1. +@end defmac -@findex FLOAT_STORE_FLAG_VALUE -@item FLOAT_STORE_FLAG_VALUE (@var{mode}) +@defmac FLOAT_STORE_FLAG_VALUE (@var{mode}) A C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is returned when comparison operators with floating-point results are true. Define this macro on machine that have comparison operations that return floating-point values. If there are no such operations, do not define this macro. +@end defmac -@findex Pmode -@item Pmode +@defmac CLZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value}) +@defmacx CTZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value}) +A C expression that evaluates to true if the architecture defines a value +for @code{clz} or @code{ctz} with a zero operand. If so, @var{value} +should be set to this value. If this macro is not defined, the value of +@code{clz} or @code{ctz} is assumed to be undefined. + +This macro must be defined if the target's expansion for @code{ffs} +relies on a particular value to get correct results. Otherwise it +is not necessary, though it may be used to optimize some corner cases. + +Note that regardless of this macro the ``definedness'' of @code{clz} +and @code{ctz} at zero do @emph{not} extend to the builtin functions +visible to the user. Thus one may be free to adjust the value at will +to match the target expansion of these operations without fear of +breaking the API. +@end defmac + +@defmac Pmode An alias for the machine mode for pointers. On most machines, define this to be the integer mode corresponding to the width of a hardware pointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines. @@ -8736,15 +8802,15 @@ The width of @code{Pmode} must be at least as large as the value of @code{POINTER_SIZE}. If it is not equal, you must define the macro @code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended to @code{Pmode}. +@end defmac -@findex FUNCTION_MODE -@item FUNCTION_MODE +@defmac FUNCTION_MODE An alias for the machine mode used for memory references to functions being called, in @code{call} RTL expressions. On most machines this should be @code{QImode}. +@end defmac -@findex INTEGRATE_THRESHOLD -@item INTEGRATE_THRESHOLD (@var{decl}) +@defmac INTEGRATE_THRESHOLD (@var{decl}) A C expression for the maximum number of instructions above which the function @var{decl} should not be inlined. @var{decl} is a @code{FUNCTION_DECL} node. @@ -8752,9 +8818,9 @@ function @var{decl} should not be inlined. @var{decl} is a The default definition of this macro is 64 plus 8 times the number of arguments that the function accepts. Some people think a larger threshold should be used on RISC machines. +@end defmac -@findex STDC_0_IN_SYSTEM_HEADERS -@item STDC_0_IN_SYSTEM_HEADERS +@defmac STDC_0_IN_SYSTEM_HEADERS In normal operation, the preprocessor expands @code{__STDC__} to the constant 1, to signify that GCC conforms to ISO Standard C@. On some hosts, like Solaris, the system compiler uses a different convention, @@ -8764,27 +8830,21 @@ strict conformance to the C Standard. Defining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host convention when processing system header files, but when processing user files @code{__STDC__} will always expand to 1. +@end defmac -@findex NO_IMPLICIT_EXTERN_C -@item NO_IMPLICIT_EXTERN_C +@defmac NO_IMPLICIT_EXTERN_C Define this macro if the system header files support C++ as well as C@. This macro inhibits the usual method of using system header files in C++, which is to pretend that the file's contents are enclosed in @samp{extern "C" @{@dots{}@}}. +@end defmac -@findex HANDLE_PRAGMA -@item HANDLE_PRAGMA (@var{getc}, @var{ungetc}, @var{name}) -This macro is no longer supported. You must use -@code{REGISTER_TARGET_PRAGMAS} instead. - -@findex REGISTER_TARGET_PRAGMAS @findex #pragma @findex pragma -@item REGISTER_TARGET_PRAGMAS (@var{pfile}) +@defmac REGISTER_TARGET_PRAGMAS () Define this macro if you want to implement any target-specific pragmas. If defined, it is a C expression which makes a series of calls to -@code{cpp_register_pragma} for each pragma, with @var{pfile} passed as -the first argument to to these functions. The macro may also do any +@code{c_register_pragma} for each pragma. The macro may also do any setup required for the pragmas. The primary reason to define this macro is to provide compatibility with @@ -8797,10 +8857,11 @@ defining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well. Preprocessor macros that appear on pragma lines are not expanded. All @samp{#pragma} directives that do not match any registered pragma are silently ignored, unless the user specifies @option{-Wunknown-pragmas}. +@end defmac -@deftypefun void cpp_register_pragma (cpp_reader *@var{pfile}, const char *@var{space}, const char *@var{name}, void (*@var{callback}) (cpp_reader *)) +@deftypefun void c_register_pragma (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *)) -Each call to @code{cpp_register_pragma} establishes one pragma. The +Each call to @code{c_register_pragma} establishes one pragma. The @var{callback} routine will be called when the preprocessor encounters a pragma of the form @@ -8814,7 +8875,7 @@ routine receives @var{pfile} as its first argument, which can be passed on to cpplib's functions if necessary. You can lex tokens after the @var{name} by calling @code{c_lex}. Tokens that are not read by the callback will be silently ignored. The end of the line is indicated by -a token of type @code{CPP_EOF}. +a token of type @code{CPP_EOF} For an example use of this routine, see @file{c4x.h} and the callback routines defined in @file{c4x-c.c}. @@ -8832,10 +8893,9 @@ rule to the makefile fragment pointed to by @code{tmake_file} that shows how to build this object file. @end deftypefun -@findex HANDLE_SYSV_PRAGMA @findex #pragma @findex pragma -@item HANDLE_SYSV_PRAGMA +@defmac HANDLE_SYSV_PRAGMA Define this macro (to a value of 1) if you want the System V style pragmas @samp{#pragma pack(<n>)} and @samp{#pragma weak <name> [=<value>]} to be supported by gcc. @@ -8863,11 +8923,11 @@ may affect its placement. The weak pragma only works if @code{SUPPORTS_WEAK} and @code{ASM_WEAKEN_LABEL} are defined. If enabled it allows the creation of specifically named weak labels, optionally with a value. +@end defmac -@findex HANDLE_PRAGMA_PACK_PUSH_POP @findex #pragma @findex pragma -@item HANDLE_PRAGMA_PACK_PUSH_POP +@defmac HANDLE_PRAGMA_PACK_PUSH_POP Define this macro (to a value of 1) if you want to support the Win32 style pragmas @samp{#pragma pack(push,@var{n})} and @samp{#pragma pack(pop)}. The @samp{pack(push,@var{n})} pragma specifies the maximum alignment @@ -8877,30 +8937,30 @@ pack value of zero resets the behavior to the default. Successive invocations of this pragma cause the previous values to be stacked, so that invocations of @samp{#pragma pack(pop)} will return to the previous value. +@end defmac -@findex DOLLARS_IN_IDENTIFIERS -@item DOLLARS_IN_IDENTIFIERS -Define this macro to control use of the character @samp{$} in identifier -names. 0 means @samp{$} is not allowed by default; 1 means it is allowed. -1 is the default; there is no need to define this macro in that case. -This macro controls the compiler proper; it does not affect the preprocessor. +@defmac DOLLARS_IN_IDENTIFIERS +Define this macro to control use of the character @samp{$} in +identifier names for the C family of languages. 0 means @samp{$} is +not allowed by default; 1 means it is allowed. 1 is the default; +there is no need to define this macro in that case. +@end defmac -@findex NO_DOLLAR_IN_LABEL -@item NO_DOLLAR_IN_LABEL +@defmac NO_DOLLAR_IN_LABEL Define this macro if the assembler does not accept the character @samp{$} in label names. By default constructors and destructors in G++ have @samp{$} in the identifiers. If this macro is defined, @samp{.} is used instead. +@end defmac -@findex NO_DOT_IN_LABEL -@item NO_DOT_IN_LABEL +@defmac NO_DOT_IN_LABEL Define this macro if the assembler does not accept the character @samp{.} in label names. By default constructors and destructors in G++ have names that use @samp{.}. If this macro is defined, these names are rewritten to avoid @samp{.}. +@end defmac -@findex DEFAULT_MAIN_RETURN -@item DEFAULT_MAIN_RETURN +@defmac DEFAULT_MAIN_RETURN Define this macro if the target system expects every program's @code{main} function to return a standard ``success'' value by default (if no other value is explicitly returned). @@ -8908,33 +8968,9 @@ value is explicitly returned). The definition should be a C statement (sans semicolon) to generate the appropriate rtl instructions. It is used only when compiling the end of @code{main}. +@end defmac -@item NEED_ATEXIT -@findex NEED_ATEXIT -Define this if the target system lacks the function @code{atexit} -from the ISO C standard. If this macro is defined, a default definition -will be provided to support C++. If @code{ON_EXIT} is not defined, -a default @code{exit} function will also be provided. - -@item ON_EXIT -@findex ON_EXIT -Define this macro if the target has another way to implement atexit -functionality without replacing @code{exit}. For instance, SunOS 4 has -a similar @code{on_exit} library function. - -The definition should be a functional macro which can be used just like -the @code{atexit} function. - -@item EXIT_BODY -@findex EXIT_BODY -Define this if your @code{exit} function needs to do something -besides calling an external function @code{_cleanup} before -terminating with @code{_exit}. The @code{EXIT_BODY} macro is -only needed if @code{NEED_ATEXIT} is defined and @code{ON_EXIT} is not -defined. - -@findex INSN_SETS_ARE_DELAYED -@item INSN_SETS_ARE_DELAYED (@var{insn}) +@defmac INSN_SETS_ARE_DELAYED (@var{insn}) Define this macro as a C expression that is nonzero if it is safe for the delay slot scheduler to place instructions in the delay slot of @var{insn}, even if they appear to use a resource set or clobbered in @var{insn}. @@ -8944,9 +8980,9 @@ or @code{jump_insn} is really a function call and hence has this behavior, you should define this macro. You need not define this macro if it would always return zero. +@end defmac -@findex INSN_REFERENCES_ARE_DELAYED -@item INSN_REFERENCES_ARE_DELAYED (@var{insn}) +@defmac INSN_REFERENCES_ARE_DELAYED (@var{insn}) Define this macro as a C expression that is nonzero if it is safe for the delay slot scheduler to place instructions in the delay slot of @var{insn}, even if they appear to set or clobber a resource referenced in @var{insn}. @@ -8958,69 +8994,53 @@ instructions which copy arguments into the argument registers into the delay slot of @var{insn}. You need not define this macro if it would always return zero. +@end defmac -@findex MACHINE_DEPENDENT_REORG -@item MACHINE_DEPENDENT_REORG (@var{insn}) -In rare cases, correct code generation requires extra machine -dependent processing between the second jump optimization pass and -delayed branch scheduling. On those machines, define this macro as a C -statement to act on the code starting at @var{insn}. - -@findex MULTIPLE_SYMBOL_SPACES -@item MULTIPLE_SYMBOL_SPACES +@defmac MULTIPLE_SYMBOL_SPACES Define this macro if in some cases global symbols from one translation unit may not be bound to undefined symbols in another translation unit without user intervention. For instance, under Microsoft Windows symbols must be explicitly imported from shared libraries (DLLs). +@end defmac -@findex MD_ASM_CLOBBERS -@item MD_ASM_CLOBBERS (@var{clobbers}) +@defmac MD_ASM_CLOBBERS (@var{clobbers}) A C statement that adds to @var{clobbers} @code{STRING_CST} trees for any hard regs the port wishes to automatically clobber for all asms. +@end defmac -@findex MAX_INTEGER_COMPUTATION_MODE -@item MAX_INTEGER_COMPUTATION_MODE -Define this to the largest integer machine mode which can be used for -operations other than load, store and copy operations. - -You need only define this macro if the target holds values larger than -@code{word_mode} in general purpose registers. Most targets should not define -this macro. - -@findex MATH_LIBRARY -@item MATH_LIBRARY +@defmac MATH_LIBRARY Define this macro as a C string constant for the linker argument to link in the system math library, or @samp{""} if the target does not have a separate math library. You need only define this macro if the default of @samp{"-lm"} is wrong. +@end defmac -@findex LIBRARY_PATH_ENV -@item LIBRARY_PATH_ENV +@defmac LIBRARY_PATH_ENV Define this macro as a C string constant for the environment variable that specifies where the linker should look for libraries. You need only define this macro if the default of @samp{"LIBRARY_PATH"} is wrong. +@end defmac -@findex TARGET_HAS_F_SETLKW -@item TARGET_HAS_F_SETLKW +@defmac TARGET_HAS_F_SETLKW Define this macro if the target supports file locking with fcntl / F_SETLKW@. Note that this functionality is part of POSIX@. Defining @code{TARGET_HAS_F_SETLKW} will enable the test coverage code to use file locking when exiting a program, which avoids race conditions if the program has forked. +@end defmac -@findex MAX_CONDITIONAL_EXECUTE -@item MAX_CONDITIONAL_EXECUTE +@defmac MAX_CONDITIONAL_EXECUTE A C expression for the maximum number of instructions to execute via conditional execution instructions instead of a branch. A value of @code{BRANCH_COST}+1 is the default if the machine does not use cc0, and 1 if it does use cc0. +@end defmac -@findex IFCVT_MODIFY_TESTS -@item IFCVT_MODIFY_TESTS(@var{ce_info}, @var{true_expr}, @var{false_expr}) +@defmac IFCVT_MODIFY_TESTS (@var{ce_info}, @var{true_expr}, @var{false_expr}) Used if the target needs to perform machine-dependent modifications on the conditionals used for turning basic blocks into conditionally executed code. @var{ce_info} points to a data structure, @code{struct ce_if_block}, which @@ -9028,47 +9048,60 @@ contains information about the currently processed blocks. @var{true_expr} and @var{false_expr} are the tests that are used for converting the then-block and the else-block, respectively. Set either @var{true_expr} or @var{false_expr} to a null pointer if the tests cannot be converted. +@end defmac -@findex IFCVT_MODIFY_MULTIPLE_TESTS -@item IFCVT_MODIFY_MULTIPLE_TESTS(@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr}) +@defmac IFCVT_MODIFY_MULTIPLE_TESTS (@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr}) Like @code{IFCVT_MODIFY_TESTS}, but used when converting more complicated if-statements into conditions combined by @code{and} and @code{or} operations. @var{bb} contains the basic block that contains the test that is currently being processed and about to be turned into a condition. +@end defmac -@findex IFCVT_MODIFY_INSN -@item IFCVT_MODIFY_INSN(@var{ce_info}, @var{pattern}, @var{insn}) +@defmac IFCVT_MODIFY_INSN (@var{ce_info}, @var{pattern}, @var{insn}) A C expression to modify the @var{PATTERN} of an @var{INSN} that is to be converted to conditional execution format. @var{ce_info} points to a data structure, @code{struct ce_if_block}, which contains information about the currently processed blocks. +@end defmac -@findex IFCVT_MODIFY_FINAL -@item IFCVT_MODIFY_FINAL(@var{ce_info}) +@defmac IFCVT_MODIFY_FINAL (@var{ce_info}) A C expression to perform any final machine dependent modifications in converting code to conditional execution. The involved basic blocks can be found in the @code{struct ce_if_block} structure that is pointed to by @var{ce_info}. +@end defmac -@findex IFCVT_MODIFY_CANCEL -@item IFCVT_MODIFY_CANCEL(@var{ce_info}) +@defmac IFCVT_MODIFY_CANCEL (@var{ce_info}) A C expression to cancel any machine dependent modifications in converting code to conditional execution. The involved basic blocks can be found in the @code{struct ce_if_block} structure that is pointed to by @var{ce_info}. +@end defmac -@findex IFCVT_INIT_EXTRA_FIELDS -@item IFCVT_INIT_EXTRA_FIELDS(@var{ce_info}) +@defmac IFCVT_INIT_EXTRA_FIELDS (@var{ce_info}) A C expression to initialize any extra fields in a @code{struct ce_if_block} structure, which are defined by the @code{IFCVT_EXTRA_FIELDS} macro. +@end defmac -@findex IFCVT_EXTRA_FIELDS -@item IFCVT_EXTRA_FIELDS +@defmac IFCVT_EXTRA_FIELDS If defined, it should expand to a set of field declarations that will be added to the @code{struct ce_if_block} structure. These should be initialized by the @code{IFCVT_INIT_EXTRA_FIELDS} macro. +@end defmac -@end table +@deftypefn {Target Hook} void TARGET_MACHINE_DEPENDENT_REORG () +If non-null, this hook performs a target-specific pass over the +instruction stream. The compiler will run it at all optimization levels, +just before the point at which it normally does delayed-branch scheduling. + +The exact purpose of the hook varies from target to target. Some use +it to do transformations that are necessary for correctness, such as +laying out in-function constant pools or avoiding hardware hazards. +Others use it as an opportunity to do some machine-dependent optimizations. + +You need not implement the hook if it has nothing to do. The default +definition is null. +@end deftypefn @deftypefn {Target Hook} void TARGET_INIT_BUILTINS () Define this hook if you have any machine-specific built-in functions @@ -9099,9 +9132,7 @@ ignored. This function should return the result of the call to the built-in function. @end deftypefn -@table @code -@findex MD_CAN_REDIRECT_BRANCH -@item MD_CAN_REDIRECT_BRANCH(@var{branch1}, @var{branch2}) +@defmac MD_CAN_REDIRECT_BRANCH (@var{branch1}, @var{branch2}) Take a branch insn in @var{branch1} and another in @var{branch2}. Return true if redirecting @var{branch1} to the destination of @@ -9110,9 +9141,9 @@ Return true if redirecting @var{branch1} to the destination of On some targets, branches may have a limited range. Optimizing the filling of delay slots can result in branches being redirected, and this may in turn cause a branch offset to overflow. +@end defmac -@findex ALLOCATE_INITIAL_VALUE -@item ALLOCATE_INITIAL_VALUE(@var{hard_reg}) +@defmac ALLOCATE_INITIAL_VALUE (@var{hard_reg}) When the initial value of a hard register has been copied in a pseudo register, it is often not necessary to actually allocate another register @@ -9130,34 +9161,34 @@ it might decide to use another register anyways. You may use @code{current_function_leaf_function} in the definition of the macro, functions that use @code{REG_N_SETS}, to determine if the hard register in question will not be clobbered. +@end defmac -@findex TARGET_OBJECT_SUFFIX -@item TARGET_OBJECT_SUFFIX +@defmac TARGET_OBJECT_SUFFIX Define this macro to be a C string representing the suffix for object files on your target machine. If you do not define this macro, GCC will use @samp{.o} as the suffix for object files. +@end defmac -@findex TARGET_EXECUTABLE_SUFFIX -@item TARGET_EXECUTABLE_SUFFIX +@defmac TARGET_EXECUTABLE_SUFFIX Define this macro to be a C string representing the suffix to be automatically added to executable files on your target machine. If you do not define this macro, GCC will use the null string as the suffix for executable files. +@end defmac -@findex COLLECT_EXPORT_LIST -@item COLLECT_EXPORT_LIST +@defmac COLLECT_EXPORT_LIST If defined, @code{collect2} will scan the individual object files specified on its command line and create an export list for the linker. Define this macro for systems like AIX, where the linker discards object files that are not referenced from @code{main} and uses export lists. +@end defmac -@findex MODIFY_JNI_METHOD_CALL -@item MODIFY_JNI_METHOD_CALL (@var{mdecl}) +@defmac MODIFY_JNI_METHOD_CALL (@var{mdecl}) Define this macro to a C expression representing a variant of the method call @var{mdecl}, if Java Native Interface (JNI) methods must be invoked differently from other methods on your target. -For example, on 32-bit Windows, JNI methods must be invoked using +For example, on 32-bit Microsoft Windows, JNI methods must be invoked using the @code{stdcall} calling convention and this macro is then defined as this expression: @@ -9167,8 +9198,7 @@ build_type_attribute_variant (@var{mdecl}, (get_identifier ("stdcall"), NULL)) @end smallexample - -@end table +@end defmac @deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) This target hook returns @code{true} past the point in which new jump @@ -9184,3 +9214,35 @@ cannot_modify_jumps_past_reload_p () @} @end smallexample @end deftypefn + +@deftypefn {Target Hook} int TARGET_BRANCH_TARGET_REGISTER_CLASS (void) +This target hook returns a register class for which branch target register +optimizations should be applied. All registers in this class should be +usable interchangeably. After reload, registers in this class will be +re-allocated and loads will be hoisted out of loops and be subjected +to inter-block scheduling. +@end deftypefn + +@deftypefn {Target Hook} bool TARGET_BRANCH_TARGET_REGISTER_CALLEE_SAVED (bool @var{after_prologue_epilogue_gen}) +Branch target register optimization will by default exclude callee-saved +registers +that are not already live during the current function; if this target hook +returns true, they will be included. The target code must than make sure +that all target registers in the class returned by +@samp{TARGET_BRANCH_TARGET_REGISTER_CLASS} that might need saving are +saved. @var{after_prologue_epilogue_gen} indicates if prologues and +epilogues have already been generated. Note, even if you only return +true when @var{after_prologue_epilogue_gen} is false, you still are likely +to have to make special provisions in @code{INITIAL_ELIMINATION_OFFSET} +to reserve space for caller-saved target registers. +@end deftypefn + +@defmac POWI_MAX_MULTS +If defined, this macro is interpreted as a signed integer C expression +that specifies the maximum number of floating point multiplications +that should be emitted when expanding exponentiation by an integer +constant inline. When this value is defined, exponentiation requiring +more than this number of multiplications is implemented by calling the +system library's @code{pow}, @code{powf} or @code{powl} routines. +The default value places no upper bound on the multiplication count. +@end defmac diff --git a/contrib/gcc/doc/trouble.texi b/contrib/gcc/doc/trouble.texi index a7e4200..a1b86bc 100644 --- a/contrib/gcc/doc/trouble.texi +++ b/contrib/gcc/doc/trouble.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001 Free Software Foundation, Inc. +@c 1999, 2000, 2001, 2003, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -129,7 +129,7 @@ Older GDB versions sometimes fail to read the output of GCC version DBX rejects some files produced by GCC, though it accepts similar constructs in output from PCC@. Until someone can supply a coherent description of what is valid DBX input and what is not, there is -nothing I can do about these problems. You are on your own. +nothing that can be done about these problems. @item The GNU assembler (GAS) does not support PIC@. To generate PIC code, you @@ -374,11 +374,11 @@ because of problems in DEC's versions of the X11 header files @option{-I/usr/include/mit} to use the MIT versions of the header files, or fixing the header files by adding this: -@example +@smallexample #ifdef __STDC__ #define NeedFunctionPrototypes 0 #endif -@end example +@end smallexample @item On various 386 Unix systems derived from System V, including SCO, ISC, @@ -393,17 +393,17 @@ is available as a separate package, and also in the file If you have installed GNU malloc as a separate library package, use this option when you relink GCC: -@example +@smallexample MALLOC=/usr/local/lib/libgmalloc.a -@end example +@end smallexample Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy the object file to @file{gmalloc.o} and use this option when you relink GCC: -@example +@smallexample MALLOC=gmalloc.o -@end example +@end smallexample @end itemize @node Incompatibilities @@ -454,9 +454,9 @@ Negating this value yields 2147483648 again. GCC does not substitute macro arguments when they appear inside of string constants. For example, the following macro in GCC -@example +@smallexample #define foo(a) "a" -@end example +@end smallexample @noindent will produce output @code{"a"} regardless of what the argument @var{a} is. @@ -469,7 +469,7 @@ variables guaranteed to remain valid are those declared @code{volatile}. This is a consequence of automatic register allocation. Consider this function: -@example +@smallexample jmp_buf j; foo () @@ -484,7 +484,7 @@ foo () /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */ return a + fun3 (); @} -@end example +@end smallexample Here @code{a} may or may not be restored to its first value when the @code{longjmp} occurs. If @code{a} is allocated in a register, then @@ -500,20 +500,19 @@ Programs that use preprocessing directives in the middle of macro arguments do not work with GCC@. For example, a program like this will not work: -@example +@smallexample @group foobar ( #define luser hack) @end group -@end example +@end smallexample ISO C does not permit such a construct. @item K&R compilers allow comments to cross over an inclusion boundary -(i.e.@: started in an include file and ended in the including file). I think -this would be quite ugly and can't imagine it could be needed. +(i.e.@: started in an include file and ended in the including file). @cindex external declaration scope @cindex scope of external declarations @@ -530,10 +529,10 @@ rest of the file even if it happens within a block. In traditional C, you can combine @code{long}, etc., with a typedef name, as shown here: -@example +@smallexample typedef int foo; typedef long foo bar; -@end example +@end smallexample In ISO C, this is not allowed: @code{long} and other type modifiers require an explicit @code{int}. @@ -546,10 +545,10 @@ PCC allows typedef names to be used as function parameters. Traditional C allows the following erroneous pair of declarations to appear together in a given scope: -@example +@smallexample typedef int foo; typedef foo foo; -@end example +@end smallexample @item GCC treats all characters of identifiers as significant. According to @@ -574,11 +573,11 @@ comments enclosed in conditionals that are guaranteed to fail; if these comments contain apostrophes, GCC will probably report an error. For example, this code would produce an error: -@example +@smallexample #if 0 You can't expect this to work. #endif -@end example +@end smallexample The best solution to such a problem is to put the text into an actual C comment delimited by @samp{/*@dots{}*/}. @@ -615,8 +614,8 @@ The method used by GCC is as follows: a structure or union which is 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union with any other size is stored into an address supplied by the caller (usually in a special, fixed register, but on some machines it is passed -on the stack). The machine-description macros @code{STRUCT_VALUE} and -@code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address. +on the stack). 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 @@ -758,14 +757,14 @@ executable and your source code, when you use optimization. Users often think it is a bug when GCC reports an error for code like this: -@example +@smallexample int foo (struct mumble *); struct mumble @{ @dots{} @}; int foo (struct mumble *x) @{ @dots{} @} -@end example +@end smallexample This code really is erroneous, because the scope of @code{struct mumble} in the prototype is limited to the argument list containing it. @@ -851,6 +850,7 @@ give rise to questions of this sort. @menu * Static Definitions:: Static member declarations are not definitions +* Name lookup:: Name lookup, templates, and accessing members of base classes * Temporaries:: Temporaries may vanish before you expect * Copy Assignment:: Copy Assignment operators copy virtual bases twice @end menu @@ -865,14 +865,14 @@ give rise to questions of this sort. When a class has static data members, it is not enough to @emph{declare} the static member; you must also @emph{define} it. For example: -@example +@smallexample class Foo @{ @dots{} void method(); static int bar; @}; -@end example +@end smallexample This declaration only establishes that the class @code{Foo} has an @code{int} named @code{Foo::bar}, and a member function named @@ -881,9 +881,9 @@ This declaration only establishes that the class @code{Foo} has an standard, you must supply an initializer in one (and only one) source file, such as: -@example +@smallexample int Foo::bar = 0; -@end example +@end smallexample Other C++ compilers may not correctly implement the standard behavior. As a result, when you switch to @command{g++} from one of these compilers, @@ -891,6 +891,130 @@ you may discover that a program that appeared to work correctly in fact does not conform to the standard: @command{g++} reports as undefined symbols any static data members that lack definitions. + +@node Name lookup +@subsection Name lookup, templates, and accessing members of base classes + +@cindex base class members +@cindex two-stage name lookup +@cindex dependent name lookup + +The C++ standard prescribes that all names that are not dependent on +template parameters are bound to their present definitions when parsing +a template function or class.@footnote{The C++ standard just uses the +term ``dependent'' for names that depend on the type or value of +template parameters. This shorter term will also be used in the rest of +this section.} Only names that are dependent are looked up at the point +of instantiation. For example, consider + +@smallexample + void foo(double); + + struct A @{ + template <typename T> + void f () @{ + foo (1); // 1 + int i = N; // 2 + T t; + t.bar(); // 3 + foo (t); // 4 + @} + + static const int N; + @}; +@end smallexample + +Here, the names @code{foo} and @code{N} appear in a context that does +not depend on the type of @code{T}. The compiler will thus require that +they are defined in the context of use in the template, not only before +the point of instantiation, and will here use @code{::foo(double)} and +@code{A::N}, respectively. In particular, it will convert the integer +value to a @code{double} when passing it to @code{::foo(double)}. + +Conversely, @code{bar} and the call to @code{foo} in the fourth marked +line are used in contexts that do depend on the type of @code{T}, so +they are only looked up at the point of instantiation, and you can +provide declarations for them after declaring the template, but before +instantiating it. In particular, if you instantiate @code{A::f<int>}, +the last line will call an overloaded @code{::foo(int)} if one was +provided, even if after the declaration of @code{struct A}. + +This distinction between lookup of dependent and non-dependent names is +called two-stage (or dependent) name lookup. G++ implements it +since version 3.4. + +Two-stage name lookup sometimes leads to situations with behavior +different from non-template codes. The most common is probably this: + +@smallexample + template <typename T> struct Base @{ + int i; + @}; + + template <typename T> struct Derived : public Base<T> @{ + int get_i() @{ return i; @} + @}; +@end smallexample + +In @code{get_i()}, @code{i} is not used in a dependent context, so the +compiler will look for a name declared at the enclosing namespace scope +(which is the global scope here). It will not look into the base class, +since that is dependent and you may declare specializations of +@code{Base} even after declaring @code{Derived}, so the compiler can't +really know what @code{i} would refer to. If there is no global +variable @code{i}, then you will get an error message. + +In order to make it clear that you want the member of the base class, +you need to defer lookup until instantiation time, at which the base +class is known. For this, you need to access @code{i} in a dependent +context, by either using @code{this->i} (remember that @code{this} is of +type @code{Derived<T>*}, so is obviously dependent), or using +@code{Base<T>::i}. Alternatively, @code{Base<T>::i} might be brought +into scope by a @code{using}-declaration. + +Another, similar example involves calling member functions of a base +class: + +@smallexample + template <typename T> struct Base @{ + int f(); + @}; + + template <typename T> struct Derived : Base<T> @{ + int g() @{ return f(); @}; + @}; +@end smallexample + +Again, the call to @code{f()} is not dependent on template arguments +(there are no arguments that depend on the type @code{T}, and it is also +not otherwise specified that the call should be in a dependent context). +Thus a global declaration of such a function must be available, since +the one in the base class is not visible until instantiation time. The +compiler will consequently produce the following error message: + +@smallexample + x.cc: In member function `int Derived<T>::g()': + x.cc:6: error: there are no arguments to `f' that depend on a template + parameter, so a declaration of `f' must be available + x.cc:6: error: (if you use `-fpermissive', G++ will accept your code, but + allowing the use of an undeclared name is deprecated) +@end smallexample + +To make the code valid either use @code{this->f()}, or +@code{Base<T>::f()}. Using the @code{-fpermissive} flag will also let +the compiler accept the code, by marking all function calls for which no +declaration is visible at the time of definition of the template for +later lookup at instantiation time, as if it were a dependent call. +We do not recommend using @code{-fpermissive} to work around invalid +code, and it will also only catch cases where functions in base classes +are called, not where variables in base classes are used (as in the +example above). + +Note that some compilers (including G++ versions prior to 3.4) get these +examples wrong and accept above code without an error. Those compilers +do not implement two-stage name lookup correctly. + + @node Temporaries @subsection Temporaries May Vanish Before You Expect @@ -910,7 +1034,7 @@ For example, a program may use a function @code{strfunc} that returns @code{string} objects, and another function @code{charfunc} that operates on pointers to @code{char}: -@example +@smallexample string strfunc (); void charfunc (const char *); @@ -923,7 +1047,7 @@ f () @dots{} charfunc (p); @} -@end example +@end smallexample @noindent In this situation, it may seem reasonable to save a pointer to the C @@ -942,10 +1066,10 @@ The safe way to write such code is to give the temporary a name, which forces it to remain until the end of the scope of the name. For example: -@example +@smallexample string& tmp = strfunc (); charfunc (tmp.c_str ()); -@end example +@end smallexample @node Copy Assignment @subsection Implicit Copy-Assignment for Virtual Bases @@ -955,7 +1079,7 @@ belongs to each full object. Also, the constructors and destructors are invoked only once, and called from the most-derived class. However, such objects behave unspecified when being assigned. For example: -@example +@smallexample struct Base@{ char *name; Base(char *n) : name(strdup(n))@{@} @@ -983,7 +1107,7 @@ void func(Derived &d1, Derived &d2) @{ d1 = d2; @} -@end example +@end smallexample The C++ standard specifies that @samp{Base::Base} is only called once when constructing or copy-constructing a Derived object. It is @@ -991,7 +1115,7 @@ unspecified whether @samp{Base::operator=} is called more than once when the implicit copy-assignment for Derived objects is invoked (as it is inside @samp{func} in the example). -g++ implements the ``intuitive'' algorithm for copy-assignment: assign all +G++ implements the ``intuitive'' algorithm for copy-assignment: assign all direct bases, then assign all members. In that algorithm, the virtual base subobject can be encountered more than once. In the example, copying proceeds in the following order: @samp{val}, @samp{name} (via @@ -1120,11 +1244,16 @@ more annoyance than good. @item Warning when a non-void function value is ignored. -Coming as I do from a Lisp background, I balk at the idea that there is -something dangerous about discarding a value. There are functions that -return values which some callers may find useful; it makes no sense to -clutter the program with a cast to @code{void} whenever the value isn't -useful. +C contains many standard functions that return a value that most +programs choose to ignore. One obvious example is @code{printf}. +Warning about this practice only leads the defensive programmer to +clutter programs with dozens of casts to @code{void}. Such casts are +required so frequently that they become visual noise. Writing those +casts becomes so automatic that they no longer convey useful +information about the intentions of the programmer. For functions +where the return value should never be ignored, use the +@code{warn_unused_result} function attribute (@pxref{Function +Attributes}). @item @opindex fshort-enums @@ -1279,12 +1408,12 @@ It is never safe to depend on the order of evaluation of side effects. For example, a function call like this may very well behave differently from one compiler to another: -@example +@smallexample void func (int, int); int i = 2; func (i++, i++); -@end example +@end smallexample There is no guarantee (in either the C or the C++ standard language definitions) that the increments will be evaluated in any particular @@ -1309,7 +1438,7 @@ an error message for a certain program. ISO C requires a ``diagnostic'' message for certain kinds of invalid programs, but a warning is defined by GCC to count as a diagnostic. If GCC produces a warning but not an error, that is correct ISO C support. -If test suites call this ``failure'', they should be run with the GCC +If testsuites call this ``failure'', they should be run with the GCC option @option{-pedantic-errors}, which will turn these warnings into errors. |