From aee96fe99b16dc13f61ebd1076b80335e8a71f8b Mon Sep 17 00:00:00 2001 From: Joseph Myers Date: Tue, 3 Jul 2001 01:46:05 +0100 Subject: [PATCH] extend.texi, [...]: Improve formatting. gcc: * doc/extend.texi, doc/gcc.texi, doc/invoke.texi, doc/md.texi, doc/rtl.texi, doc/tm.texi: Improve formatting. Improve documentation of -std and -Wwrite-strings. contrib: * texi2pod.pl: Handle @r inside @item. From-SVN: r43718 --- contrib/ChangeLog | 4 + contrib/texi2pod.pl | 7 +- gcc/ChangeLog | 6 ++ gcc/doc/extend.texi | 27 ++++-- gcc/doc/gcc.texi | 14 +-- gcc/doc/invoke.texi | 214 +++++++++++++++++++++++--------------------- gcc/doc/md.texi | 6 +- gcc/doc/rtl.texi | 5 +- gcc/doc/tm.texi | 139 ++++++++++++++-------------- 9 files changed, 227 insertions(+), 195 deletions(-) diff --git a/contrib/ChangeLog b/contrib/ChangeLog index bd0825e2332..7279ad9adcd 100644 --- a/contrib/ChangeLog +++ b/contrib/ChangeLog @@ -1,3 +1,7 @@ +2001-07-03 Joseph S. Myers + + * texi2pod.pl: Handle @r inside @item. + 2001-07-02 Zack Weinberg * gcc_update: Remove entries for gcc.1, cpp.1, gcov.1. diff --git a/contrib/texi2pod.pl b/contrib/texi2pod.pl index d70b44880a2..7a930eed595 100755 --- a/contrib/texi2pod.pl +++ b/contrib/texi2pod.pl @@ -279,9 +279,6 @@ sub postprocess s/\@w\{([^\}]*)\}/S<$1>/g; s/\@(?:dmn|math)\{([^\}]*)\}/$1/g; - # Handle @r inside bold. - 1 while s/B<((?:[^<>]|I<[^<>]*>)*)R<([^>]*)>/B<$1>${2}B blah> into B I B to - # match Texinfo semantics of @emph inside @samp. + # match Texinfo semantics of @emph inside @samp. Also handle @r + # inside bold. s/<//g; + 1 while s/B<((?:[^<>]|I<[^<>]*>)*)R<([^>]*)>/B<$1>${2}B]*)I<([^>]+)>/B<$1>I<$2>B]*)B<([^>]+)>/I<$1>B<$2>I//g; diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 5b45aab9c3a..01d855ab607 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,9 @@ +2001-07-03 Joseph S. Myers + + * doc/extend.texi, doc/gcc.texi, doc/invoke.texi, doc/md.texi, + doc/rtl.texi, doc/tm.texi: Improve formatting. Improve + documentation of -std and -Wwrite-strings. + 2001-07-02 Geoffrey Keating * cse.c (canon_hash): Don't register registers in very small diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 28835fb2e38..f08be3b426e 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -387,6 +387,7 @@ called @dfn{lexical scoping}. For example, here we show a nested function which uses an inherited variable named @code{offset}: @example +@group bar (int *array, int offset, int size) @{ int access (int *array, int index) @@ -396,6 +397,7 @@ bar (int *array, int offset, int size) for (i = 0; i < size; i++) @dots{} access (array, i) @dots{} @} +@end group @end example Nested function definitions are permitted within functions in the places @@ -886,7 +888,13 @@ conforming) and in C++. In that format the @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are mandatory. The exponent is a decimal number that indicates the power of 2 by which the significant part will be multiplied. Thus @samp{0x1.f} is -1 15/16, @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} +@tex +$1 {15\over16}$, +@end tex +@ifnottex +1 15/16, +@end ifnottex +@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} is the same as @code{1.55e1}. Unlike for floating-point numbers in the decimal notation the exponent @@ -1493,7 +1501,7 @@ double y; @end example @noindent -both @code{x} and @code{y} can be cast to type @code{union} foo. +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: @@ -1581,6 +1589,7 @@ their own functions that never return. You can declare them @code{noreturn} to tell the compiler this fact. For example, @smallexample +@group void fatal () __attribute__ ((noreturn)); void @@ -1589,6 +1598,7 @@ fatal (@dots{}) @dots{} /* @r{Print error message.} */ @dots{} exit (1); @} +@end group @end smallexample The @code{noreturn} keyword tells the compiler to assume that @@ -1973,7 +1983,8 @@ alternate stack. @smallexample void *alt_stack; -void f () __attribute__ ((interrupt_handler, sp_switch ("alt_stack"))); +void f () __attribute__ ((interrupt_handler, + sp_switch ("alt_stack"))); @end smallexample @item trap_exit @@ -3181,7 +3192,7 @@ asm volatile ("eieio" : : ); @noindent Assume @code{addr} contains the address of a memory mapped device register. The PowerPC @code{eieio} instruction (Enforce In-order -Execution of I/O) tells the cpu to make sure that the store to that +Execution of I/O) tells the CPU to make sure that the store to that device register happens before it issues any other I/O@. Note that even a volatile @code{asm} instruction can be moved in ways @@ -4725,20 +4736,20 @@ and will be removed from g++ at some point. @cindex Backwards Compatibility @cindex ARM [Annotated C++ Reference Manual] -Now that there is a definitive ISO standard C++, g++ has a specification +Now that there is a definitive ISO standard C++, G++ has a specification to adhere to. The C++ language evolved over time, and features that used to be acceptable in previous drafts of the standard, such as the ARM [Annotated C++ Reference Manual], are no longer accepted. In order to allow -compilation of C++ written to such drafts, g++ contains some backwards +compilation of C++ written to such drafts, G++ contains some backwards compatibilities. @emph{All such backwards compatibility features are -liable to disappear in future versions of g++.} They should be considered +liable to disappear in future versions of G++.} They should be considered deprecated @xref{Deprecated Features}. @table @code @item For scope If a variable is declared at for scope, it used to remain in scope until the end of the scope which contained the for statement (rather than just -within the for scope). g++ retains this, but issues a warning, if such a +within the for scope). G++ retains this, but issues a warning, if such a variable is accessed outside the for scope. @item implicit C language diff --git a/gcc/doc/gcc.texi b/gcc/doc/gcc.texi index d20e6b557aa..fb4eb6a6245 100644 --- a/gcc/doc/gcc.texi +++ b/gcc/doc/gcc.texi @@ -188,7 +188,7 @@ included in the section entitled ``GNU Free Documentation License''. @sp 1 @c The version number appears five times more in this file. -@center for gcc-3.1 +@center for GCC 3.1 @page @vskip 0pt plus 1filll Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998, @@ -197,7 +197,7 @@ Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998, For GCC Version 3.1@* @sp 1 Published by the Free Software Foundation @* -59 Temple Place - Suite 330@* +59 Temple Place---Suite 330@* Boston, MA 02111-1307, USA@* Last printed April, 1998.@* Printed copies are available for $50 each.@* @@ -1143,9 +1143,11 @@ arguments do not work with GCC@. For example, a program like this will not work: @example +@group foobar ( #define luser hack) +@end group @end example ISO C does not permit such a construct. It would make sense to support @@ -3214,12 +3216,12 @@ 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{class.c}, @file{cvt.c}, @file{decl.c}, @file{decl2.c}, -@file{except.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{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}, diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 251530a9fbe..4b01442ecd9 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -237,7 +237,8 @@ in the following sections. @xref{Debugging Options,,Options for Debugging Your Program or GCC}. @gccoptlist{ -a -ax -d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol --fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol +-fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol +-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol -fdump-ast-original@r{[}-@var{n}@r{]} -fdump-ast-optimized@r{[}-@var{n}@r{]} @gol -fdump-ast-inlined@r{[}-@var{n}@r{]} @gol -fmem-report -fpretend-float @gol @@ -288,12 +289,12 @@ in the following sections. -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}} +-trigraphs -undef -U@var{macro} -Wp,@var{option}} @item Assembler Option @xref{Assembler Options,,Passing Options to the Assembler}. @gccoptlist{ --Wa\,@var{option}} +-Wa,@var{option}} @item Linker Options @xref{Link Options,,Options for Linking}. @@ -301,7 +302,7 @@ in the following sections. @var{object-file-name} -l@var{library} @gol -nostartfiles -nodefaultlibs -nostdlib @gol -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol --Wl\,@var{option} -Xlinker @var{option} @gol +-Wl,@var{option} -Xlinker @var{option} @gol -u @var{symbol}} @item Directory Options @@ -526,7 +527,7 @@ in the following sections. @emph{System V Options} @gccoptlist{ --Qy -Qn -YP\,@var{paths} -Ym\,@var{dir}} +-Qy -Qn -YP,@var{paths} -Ym,@var{dir}} @emph{ARC Options} @gccoptlist{ @@ -876,7 +877,7 @@ In C mode, support all ISO C89 programs. In C++ mode, remove GNU extensions that conflict with ISO C++. This turns off certain features of GCC that are incompatible with ISO -C (when compiling C code), or of standard C++ (when compiling C++ code), +C89 (when compiling C code), or of standard C++ (when compiling C++ code), such as the @code{asm} and @code{typeof} keywords, and predefined macros such as @code{unix} and @code{vax} that identify the type of system you are using. It also enables the undesirable and @@ -910,40 +911,33 @@ affected. @item -std= @opindex std -Determine the language standard. A value for this option must be provided; +Determine the language standard. This option is currently only +supported when compiling C@. A value for this option must be provided; possible values are @table @samp -@item iso9899:1990 -Same as @option{-ansi} +@item c89 +@itemx iso9899:1990 +ISO C89 (same as @option{-ansi}). @item iso9899:199409 -ISO C as modified in amendment 1 - -@item iso9899:1999 -ISO C99. Note that this standard is not yet fully supported; see -@w{@uref{http://gcc.gnu.org/c99status.html}} for more information. - -@item c89 -same as @option{-std=iso9899:1990} +ISO C89 as modified in amendment 1. @item c99 -same as @option{-std=iso9899:1999} +@itemx c9x +@itemx iso9899:1999 +@itemx iso9899:199x +ISO C99. Note that this standard is not yet fully supported; see +@w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The +names @samp{c9x} and @samp{iso9899:199x} are deprecated. @item gnu89 -default, iso9899:1990 + gnu extensions +Default, ISO C89 plus GNU extensions (including some C99 features). @item gnu99 -iso9899:1999 + gnu extensions - -@item iso9899:199x -same as @option{-std=iso9899:1999}, deprecated - -@item c9x -same as @option{-std=iso9899:1999}, deprecated - -@item gnu9x -same as @option{-std=gnu99}, deprecated +@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. @end table @@ -1268,7 +1262,7 @@ this check is normally unnecessary. An alternative to using this option is to specify that your @code{operator new} does not throw any exceptions; if you declare it -@samp{throw()}, g++ will check the return value. See also @samp{new +@samp{throw()}, G++ will check the return value. See also @samp{new (nothrow)}. @item -fconserve-space @@ -1307,7 +1301,7 @@ identifiers. However, ISO C and C++ forbid @samp{$} in identifiers. @opindex fno-elide-constructors The C++ standard allows an implementation to omit creating a temporary which is only used to initialize another object of the same type. -Specifying this option disables that optimization, and forces g++ to +Specifying this option disables that optimization, and forces G++ to call the copy constructor in all cases. @item -fno-enforce-eh-specs @@ -1343,7 +1337,7 @@ a @i{for-init-statement} is limited to the @samp{for} loop itself, as specified by the C++ standard. If @option{-fno-for-scope} is specified, the scope of variables declared in a @i{for-init-statement} extends to the end of the enclosing scope, -as was the case in old versions of gcc, and other (traditional) +as was the case in old versions of G++, and other (traditional) implementations of C++. The default if neither flag is given to follow the standard, @@ -1407,13 +1401,13 @@ synonyms as keywords. @item -fno-optional-diags @opindex fno-optional-diags Disable diagnostics that the standard says a compiler does not need to -issue. Currently, the only such diagnostic issued by g++ is the one for +issue. Currently, the only such diagnostic issued by G++ is the one for a name having multiple meanings within a class. @item -fpermissive @opindex fpermissive Downgrade messages about nonconformant code from errors to warnings. By -default, g++ effectively sets @option{-pedantic-errors} without +default, G++ effectively sets @option{-pedantic-errors} without @option{-pedantic}; this option reverses that. This behavior and this option are superseded by @option{-pedantic}, which works as it does for GNU C@. @@ -1489,18 +1483,18 @@ Do not assume @samp{inline} for functions defined inside a class scope. functions will have linkage like inline functions; they just won't be inlined by default. -@item -Wctor-dtor-privacy (C++ only) +@item -Wctor-dtor-privacy @r{(C++ only)} @opindex Wctor-dtor-privacy Warn when a class seems unusable, because all the constructors or destructors in a class are private and the class has no friends or public static member functions. -@item -Wnon-virtual-dtor (C++ only) +@item -Wnon-virtual-dtor @r{(C++ only)} @opindex Wnon-virtual-dtor Warn when a class declares a non-virtual destructor that should probably be virtual, because it looks like the class will be used polymorphically. -@item -Wreorder (C++ only) +@item -Wreorder @r{(C++ only)} @opindex Wreorder @cindex reordering, warning @cindex warning for reordering of member initializers @@ -1523,41 +1517,41 @@ members. The following @option{-W@dots{}} options are not affected by @option{-Wall}. @table @gcctabopt -@item -Weffc++ (C++ only) +@item -Weffc++ @r{(C++ only)} @opindex Weffc++ Warn about violations of various style guidelines from Scott Meyers' @cite{Effective C++} books. If you use this option, you should be aware that the standard library headers do not obey all of these guidelines; you can use @samp{grep -v} to filter out those warnings. -@item -Wno-deprecated (C++ only) +@item -Wno-deprecated @r{(C++ only)} @opindex Wno-deprecated Do not warn about usage of deprecated features. @xref{Deprecated Features}. -@item -Wno-non-template-friend (C++ only) +@item -Wno-non-template-friend @r{(C++ only)} @opindex Wno-non-template-friend Disable warnings when non-templatized friend functions are declared within a template. With the advent of explicit template specification -support in g++, if the name of the friend is an unqualified-id (i.e., +support in G++, if the name of the friend is an unqualified-id (i.e., @samp{friend foo(int)}), the C++ language specification demands that the friend declare or define an ordinary, nontemplate function. (Section -14.5.3). Before g++ implemented explicit specification, unqualified-ids +14.5.3). Before G++ implemented explicit specification, unqualified-ids could be interpreted as a particular specialization of a templatized function. Because this non-conforming behavior is no longer the default -behavior for g++, @option{-Wnon-template-friend} allows the compiler to +behavior for G++, @option{-Wnon-template-friend} allows the compiler to check existing code for potential trouble spots, and is on by default. This new compiler behavior can be turned off with @option{-Wno-non-template-friend} which keeps the conformant compiler code but disables the helpful warning. -@item -Wold-style-cast (C++ only) +@item -Wold-style-cast @r{(C++ only)} @opindex Wold-style-cast Warn if an old-style (C-style) cast is used within a C++ program. The new-style casts (@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are less vulnerable to unintended effects, and much easier to grep for. -@item -Woverloaded-virtual (C++ only) +@item -Woverloaded-virtual @r{(C++ only)} @opindex Woverloaded-virtual @cindex overloaded virtual fn, warning @cindex warning for overloaded virtual fn @@ -1584,23 +1578,23 @@ b->f(); will fail to compile. -@item -Wno-pmf-conversions (C++ only) +@item -Wno-pmf-conversions @r{(C++ only)} @opindex Wno-pmf-conversions Disable the diagnostic for converting a bound pointer to member function to a plain pointer. -@item -Wsign-promo (C++ only) +@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 -the same size. Previous versions of g++ would try to preserve +the same size. Previous versions of G++ would try to preserve unsignedness, but the standard mandates the current behavior. -@item -Wsynth (C++ only) +@item -Wsynth @r{(C++ only)} @opindex Wsynth @cindex warning for synthesized methods @cindex synthesized methods, warning -Warn when g++'s synthesis behavior does not match that of cfront. For +Warn when G++'s synthesis behavior does not match that of cfront. For instance: @smallexample @@ -1616,7 +1610,7 @@ main () @} @end smallexample -In this example, g++ will synthesize a default @samp{A& operator = +In this example, G++ will synthesize a default @samp{A& operator = (const A&);}, while cfront will use the user-defined @samp{operator =}. @end table @@ -1697,7 +1691,7 @@ the remaining front ends would be able to digest them correctly. @item -fmessage-length=@var{n} @opindex fmessage-length Try to format error messages so that they fit on lines of about @var{n} -characters. The default is 72 characters for g++ and 0 for the rest of +characters. The default is 72 characters for @command{g++} and 0 for the rest of the front ends supported by GCC@. If @var{n} is zero, then no line-wrapping will be done; each error message will appear on a single line. @@ -1922,6 +1916,7 @@ Also warn about constructions where there may be confusion to which such a case: @smallexample +@group @{ if (a) if (b) @@ -1929,6 +1924,7 @@ such a case: else bar (); @} +@end group @end smallexample In C, every @code{else} branch belongs to the innermost possible @code{if} @@ -1941,6 +1937,7 @@ To eliminate the warning, add explicit braces around the innermost the enclosing @code{if}. The resulting code would look like this: @smallexample +@group @{ if (a) @{ @@ -1950,6 +1947,7 @@ the enclosing @code{if}. The resulting code would look like this: bar (); @} @} +@end group @end smallexample @item -Wsequence-point @@ -2088,6 +2086,7 @@ despite appearing to have an error. Here is one example of how this can happen: @smallexample +@group @{ int x; switch (y) @@ -2100,6 +2099,7 @@ this can happen: @} foo (x); @} +@end group @end smallexample @noindent @@ -2134,7 +2134,7 @@ Some spurious warnings can be avoided if you declare all the functions you use that never return as @code{noreturn}. @xref{Function Attributes}. -@item -Wreorder (C++ only) +@item -Wreorder @r{(C++ only)} @opindex Wreorder @cindex reordering, warning @cindex warning for reordering of member initializers @@ -2273,7 +2273,7 @@ would check to see whether the two values have ranges that overlap; and this is done with the relational operators, so equality comparisons are probably mistaken. -@item -Wtraditional (C only) +@item -Wtraditional @r{(C only)} @opindex Wtraditional Warn about certain constructs that behave differently in traditional and ISO C@. Also warn about ISO C constructs that have no traditional C @@ -2372,7 +2372,7 @@ of @code{void}. GNU C assigns these types a size of 1, for convenience in calculations with @code{void *} pointers and pointers to functions. -@item -Wbad-function-cast (C only) +@item -Wbad-function-cast @r{(C only)} @opindex Wbad-function-cast Warn whenever a function call is cast to a non-matching type. For example, warn if @code{int malloc()} is cast to @code{anything *}. @@ -2392,9 +2392,12 @@ two- or four-byte boundaries. @item -Wwrite-strings @opindex Wwrite-strings -Give string constants the type @code{const char[@var{length}]} so that +When compiling C, give string constants the type @code{const +char[@var{length}]} so that copying the address of one into a non-@code{const} @code{char *} -pointer will get a warning. These warnings will help you find at +pointer will get a warning; when compiling C++, warn about the +deprecated conversion from string constants to @code{char *}. +These warnings will help you find at compile time code that can try to write into a string constant, but only if you have been very careful about using @code{const} in declarations and prototypes. Otherwise, it will just be a nuisance; @@ -2429,14 +2432,14 @@ Warn if any functions that return structures or unions are defined or called. (In languages where you can return an array, this also elicits a warning.) -@item -Wstrict-prototypes (C only) +@item -Wstrict-prototypes @r{(C only)} @opindex Wstrict-prototypes Warn if a function is declared or defined without specifying the argument types. (An old-style function definition is permitted without a warning if preceded by a declaration which specifies the argument types.) -@item -Wmissing-prototypes (C only) +@item -Wmissing-prototypes @r{(C only)} @opindex Wmissing-prototypes Warn if a global function is defined without a previous prototype declaration. This warning is issued even if the definition itself @@ -2505,7 +2508,7 @@ reduce the padding and so make the structure smaller. Warn if anything is declared more than once in the same scope, even in cases where multiple declaration is valid and changes nothing. -@item -Wnested-externs (C only) +@item -Wnested-externs @r{(C only)} @opindex Wnested-externs Warn if an @code{extern} declaration is encountered within a function. @@ -2992,16 +2995,16 @@ numbers and line number note output. This makes it more feasible to use diff on debugging dumps for compiler invocations with different options, in particular with and without @option{-g}. -@item -fdump-translation-unit (C and C++ only) -@item -fdump-translation-unit-@var{number} (C and C++ only) +@item -fdump-translation-unit @r{(C and C++ only)} +@itemx -fdump-translation-unit-@var{number} @r{(C and C++ only)} @opindex fdump-translation-unit Dump a representation of the tree structure for the entire translation unit to a file. The file name is made by appending @file{.tu} to the source file name. If the @samp{-@var{number}} form is used, @var{number} controls the details of the dump as described for the @option{-fdump-tree} options. -@item -fdump-class-hierarchy (C++ only) -@item -fdump-class-hierarchy-@var{number} (C++ only) +@item -fdump-class-hierarchy @r{(C++ only)} +@itemx -fdump-class-hierarchy-@var{number} @r{(C++ only)} @opindex fdump-class-hierarchy Dump a representation of each class's hierarchy and virtual function table layout to a file. The file name is made by appending @file{.class} @@ -3009,8 +3012,8 @@ to the source file name. If the @samp{-@var{number}} form is used, @var{number} controls the details of the dump as described for the @option{-fdump-tree} options. -@item -fdump-ast-@var{switch} (C++ only) -@item -fdump-ast-@var{switch}-@var{number} (C++ only) +@item -fdump-ast-@var{switch} @r{(C++ only)} +@itemx -fdump-ast-@var{switch}-@var{number} @r{(C++ only)} @opindex fdump-ast Control the dumping at various stages of processing the abstract syntax tree to a file. The file name is generated by appending a switch @@ -3314,11 +3317,11 @@ allows the control of this limit for functions that are explicitly marked as inline (ie 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 number of pseudo instructions (not counting parameter handling). The default -value of n is 10000. Increasing this value can result in more inlined code at +value of @var{n} is 10000. Increasing this value can result in more inlined code at the cost of compilation time and memory consumption. Decreasing usually makes the compilation faster and less code will be inlined (which presumably means slower programs). This option is particularly useful for programs that -use inlining heavily such as those based on recursive templates with c++. +use inlining heavily such as those based on recursive templates with C++. @emph{Note:} pseudo instruction represents, in this particular context, an abstract measurement of function's size. In no way, it represents a count @@ -3482,7 +3485,7 @@ can be changed to a load before the loop and a store after the loop. Use global dataflow analysis to identify and eliminate useless null pointer checks. Programs which rely on NULL pointer dereferences @emph{not} halting the program may not work properly with this option. Use --fno-delete-null-pointer-checks to disable this optimizing for programs +@option{-fno-delete-null-pointer-checks} to disable this optimizing for programs which depend on that behavior. @item -fexpensive-optimizations @@ -4093,31 +4096,31 @@ converts them. See the @option{-std} and @option{-ansi} options. The nine trigraph sequences are @table @samp @item ??( --> @samp{[} +@expansion{} @samp{[} @item ??) --> @samp{]} +@expansion{} @samp{]} @item ??< --> @samp{@{} +@expansion{} @samp{@{} @item ??> --> @samp{@}} +@expansion{} @samp{@}} @item ??= --> @samp{#} +@expansion{} @samp{#} @item ??/ --> @samp{\} +@expansion{} @samp{\} @item ??' --> @samp{^} +@expansion{} @samp{^} @item ??! --> @samp{|} +@expansion{} @samp{|} @item ??- --> @samp{~} +@expansion{} @samp{~} @end table @@ -4125,7 +4128,7 @@ Trigraph support is not popular, so many compilers do not implement it properly. Portable code should not rely on trigraphs being either converted or ignored. -@item -Wp\,@var{option} +@item -Wp,@var{option} @opindex Wp Pass @var{option} as an option to the preprocessor. If @var{option} contains commas, it is split into multiple options at the commas. @@ -4138,7 +4141,7 @@ contains commas, it is split into multiple options at the commas. You can pass options to the assembler. @table @gcctabopt -@item -Wa\,@var{option} +@item -Wa,@var{option} @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. @@ -4327,7 +4330,7 @@ For example, to pass @option{-assert definitions}, you must write @option{-Xlinker "-assert definitions"}, because this passes the entire string as a single argument, which is not what the linker expects. -@item -Wl\,@var{option} +@item -Wl,@var{option} @opindex Wl Pass @var{option} as an option to the linker. If @var{option} contains commas, it is split into multiple options at the commas. @@ -4427,8 +4430,8 @@ the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment Variables}. As a special kludge, if the path provided by @option{-B} is -@samp{[foo/]stage/} then it will be replaced by -@samp{[foo/]include}. This is to help with boot-strapping the compiler. +@file{[foo/]stage@var{N}/} then it will be replaced by +@file{[foo/]include}. This is to help with boot-strapping the compiler. @item -specs=@var{file} @opindex specs @@ -4638,7 +4641,7 @@ simply substituted with a file name chosen for the previous @samp{%u}, without regard to any appended suffix. @item %j@var{SUFFIX} -Substitutes the name of the HOST_BIT_BUCKET, if any, and if it is +Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is writable, and if save-temps is off; otherwise, substitute the name of a temporary file, just like @samp{%u}. This temporary file is not meant for communication between processes, but rather as a junk @@ -4683,7 +4686,7 @@ predefined macro, except for macros that start with @samp{__} or with C@. @item %I -Substitute a @option{-iprefix} option made from GCC_EXEC_PREFIX@. +Substitute a @option{-iprefix} option made from @env{GCC_EXEC_PREFIX}. @item %s Current argument is the name of a library or startup file of some sort. @@ -5373,7 +5376,7 @@ With @option{-mflat}, the compiler does not generate save/restore instructions and will use a ``flat'' or single register window calling convention. This model uses %i7 as the frame pointer and is compatible with the normal register window model. Code from either may be intermixed. -The local registers and the input registers (0-5) are still treated as +The local registers and the input registers (0--5) are still treated as ``call saved'' registers and will be saved on the stack as necessary. With @option{-mno-flat} (the default), the compiler emits save/restore @@ -5936,12 +5939,16 @@ compiler is built for cross-compilation. @opindex mcpu This specifies the name of the target ARM processor. GCC uses this name to determine what kind of instructions it can emit when generating -assembly code. Permissible names are: arm2, arm250, arm3, arm6, arm60, -arm600, arm610, arm620, arm7, arm7m, arm7d, arm7dm, arm7di, arm7dmi, -arm70, arm700, arm700i, arm710, arm710c, arm7100, arm7500, arm7500fe, -arm7tdmi, arm8, strongarm, strongarm110, strongarm1100, arm8, arm810, -arm9, arm9e, arm920, arm920t, arm940t, arm9tdmi, arm10tdmi, arm1020t, -xscale. +assembly code. Permissible names are: @samp{arm2}, @samp{arm250}, +@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610}, +@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm}, +@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700}, +@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100}, +@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}. @itemx -mtune=@var{name} @opindex mtune @@ -5959,8 +5966,9 @@ this option. This specifies the name of the target ARM architecture. GCC uses this 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: armv2, armv2a, -armv3, armv3m, armv4, armv4t, armv5, armv5t, armv5te. +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}. @item -mfpe=@var{number} @itemx -mfp=@var{number} @@ -6018,7 +6026,7 @@ pointers. @item -mnop-fun-dllimport @opindex mnop-fun-dllimport -Disable support for the @emph{dllimport} attribute. +Disable support for the @code{dllimport} attribute. @item -msingle-pic-base @opindex msingle-pic-base @@ -7119,7 +7127,7 @@ the default if the configure option @option{--with-gnu-as} is used. @opindex msplit-addresses @opindex mno-split-addresses Generate code to load the high and low parts of address constants separately. -This allows @code{gcc} to optimize away redundant loads of the high order +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. @@ -8236,12 +8244,12 @@ Identify the versions of each tool used by the compiler, in a Refrain from adding @code{.ident} directives to the output file (this is the default). -@item -YP\,@var{dirs} +@item -YP,@var{dirs} @opindex YP Search the directories @var{dirs}, and no others, for libraries specified with @option{-l}. -@item -Ym\,@var{dir} +@item -Ym,@var{dir} @opindex Ym Look in the directory @var{dir} to find the M4 preprocessor. The assembler uses this option. @@ -8294,8 +8302,8 @@ count register BK@. Enable (disable) generation of code using decrement and branch, DBcond(D), instructions. This is enabled by default for the C4x. To be on the safe side, this is disabled for the C3x, since the maximum -iteration count on the C3x is 2^23 + 1 (but who iterates loops more than -2^23 times on the C3x?). Note that GCC will try to reverse a loop so +iteration count on the C3x is @math{2^23 + 1} (but who iterates loops more than +@math{2^23} times on the C3x?). Note that GCC will try to reverse a loop so that it can utilise the decrement and branch instruction, but will give up if there is more than one memory reference in the loop. Thus a loop where the loop counter is decremented can generate slightly more @@ -8363,9 +8371,9 @@ instruction, it is disabled by default. @opindex mloop-unsigned @opindex mno-loop-unsigned The maximum iteration count when using RPTS and RPTB (and DB on the C40) -is 2^31 + 1 since these instructions test if the iteration count is +is @math{2^31 + 1} since these instructions test if the iteration count is negative to terminate the loop. If the iteration count is unsigned -there is a possibility than the 2^31 + 1 maximum iteration count may be +there is a possibility than the @math{2^31 + 1} maximum iteration count may be exceeded. This switch allows an unsigned iteration count. @item -mti @@ -8681,7 +8689,7 @@ Output instruction sizes to the asm file. @item -minit-stack=@var{N} @opindex minit-stack Specify the initial stack address, which may be a symbol or numeric value, -__stack is the default. +@samp{__stack} is the default. @item -mno-interrupts @opindex mno-interrupts diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi index 3d4d2b1a6d5..06c8e3fd738 100644 --- a/gcc/doc/md.texi +++ b/gcc/doc/md.texi @@ -79,7 +79,7 @@ If a @code{define_insn} is used, the template given is inserted into the insn list. If a @code{define_expand} is used, one of three things happens, based on the condition logic. The condition logic may manually create new insns for the insn list, say via @code{emit_insn()}, and -invoke DONE@. For certain named patterns, it may invoke FAIL to tell the +invoke @code{DONE}. For certain named patterns, it may invoke @code{FAIL} to tell the compiler to use an alternate way of performing that task. If it invokes neither @code{DONE} nor @code{FAIL}, the template given in the pattern is inserted, as if the @code{define_expand} were a @code{define_insn}. @@ -1632,7 +1632,7 @@ Constant in range 0 to 63 (for 64-bit shifts) Constant in range 0 to 255 (for @code{out} instruction) @item Z -Constant in range 0 to 0xffffffff or symbolic reference known to fit specified range. +Constant in range 0 to @code{0xffffffff} or symbolic reference known to fit specified range. (for using immediates in zero extending 32-bit to 64-bit x86-64 instructions) @item e @@ -3827,7 +3827,7 @@ from i386.md: @end smallexample In this case, the actual split condition will be -"TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed." +@samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}. The @code{define_insn_and_split} construction provides exactly the same functionality as two separate @code{define_insn} and @code{define_split} diff --git a/gcc/doc/rtl.texi b/gcc/doc/rtl.texi index 618322a43c3..922828f8f78 100644 --- a/gcc/doc/rtl.texi +++ b/gcc/doc/rtl.texi @@ -1793,7 +1793,7 @@ are filled to an entire word with zeros instead of by sign-extension. @section Vector Operations @cindex vector operations -All normal rtl expressions can be used with vector modes; they are +All normal RTL expressions can be used with vector modes; they are interpreted as operating on each part of the vector independently. Additionally, there are a few new expressions to describe specific vector operations. @@ -2360,7 +2360,8 @@ where @var{z} is an index register and @var{i} is a constant. Here is an example of its use: @example -(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42) (reg:SI 48)))) +(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42) + (reg:SI 48)))) @end example This says to modify pseudo register 42 by adding the contents of pseudo diff --git a/gcc/doc/tm.texi b/gcc/doc/tm.texi index 81aa6b9726c..7a1d8bce34b 100644 --- a/gcc/doc/tm.texi +++ b/gcc/doc/tm.texi @@ -376,7 +376,7 @@ the effect you need. @findex LINK_ELIMINATE_DUPLICATE_LDIRECTORIES @item LINK_ELIMINATE_DUPLICATE_LDIRECTORIES -A nonzero value causes collect2 to remove duplicate -L search +A nonzero value causes 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. @@ -804,7 +804,7 @@ RTX to hold the register containing the function's return address. This RTX can then be used to implement the @code{__builtin_return_address} function, for level 0. -Note - earlier implementations of GCC used a single data area to hold +Note---earlier implementations of GCC used a single data area to hold all of the per-function information. Thus when processing of a nested function began the old per-function data had to be pushed onto a stack, and when the processing was finished, it had to be popped off the @@ -886,9 +886,9 @@ macro need not be a constant. @findex LIBGCC2_WORDS_BIG_ENDIAN @item LIBGCC2_WORDS_BIG_ENDIAN -Define this macro if WORDS_BIG_ENDIAN is not constant. This must be a -constant value with the same meaning as WORDS_BIG_ENDIAN, which will be -used only when compiling libgcc2.c. Typically the value will be set +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. @findex FLOAT_WORDS_BIG_ENDIAN @@ -996,15 +996,15 @@ size of an integer. Define this macro if there is a guaranteed alignment 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 PREFERRED_STACK_BOUNDARY is not defined. +default if @code{PREFERRED_STACK_BOUNDARY} is not defined. @findex PREFERRED_STACK_BOUNDARY @item PREFERRED_STACK_BOUNDARY Define this macro if you wish to preserve a certain alignment for the stack pointer. The definition is a C expression -for the desired alignment (measured in bits). If STACK_BOUNDARY is +for the desired alignment (measured in bits). If @code{STACK_BOUNDARY} is also defined, this macro must evaluate to a value equal to or larger -than STACK_BOUNDARY@. +than @code{STACK_BOUNDARY}. @cindex @code{PUSH_ROUNDING}, interaction with @code{PREFERRED_STACK_BOUNDARY} If @code{PUSH_ROUNDING} is not defined, the stack will always be aligned @@ -1925,7 +1925,7 @@ The byte offset. @item YMODE The mode of a top level SUBREG (or what may become one). @end table -The default function can be found in rtlanal.c, function +The default function can be found in @file{rtlanal.c}, function @code{subreg_regno_offset}. Normally this does not need to be defined. @end table @@ -2628,7 +2628,7 @@ You only need to define this macro if you want to support call frame debugging information like that provided by DWARF 2. If this RTL is a @code{REG}, you should also define -DWARF_FRAME_RETURN_COLUMN to @code{DWARF_FRAME_REGNUM (REGNO)}. +@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}. @findex INCOMING_FRAME_SP_OFFSET @item INCOMING_FRAME_SP_OFFSET @@ -2708,14 +2708,14 @@ If you want to support call frame exception handling, you must define either this macro or the @code{eh_return} instruction pattern. @findex ASM_PREFERRED_EH_DATA_FORMAT -@item ASM_PREFERRED_EH_DATA_FORMAT(@var{CODE}, @var{GLOBAL}) +@item 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, and so may be read-only. -@var{CODE} is 0 for data, 1 for code labels, 2 for function pointers. -@var{GLOBAL} is true if the symbol may be affected by dynamic relocations. +@var{code} is 0 for data, 1 for code labels, 2 for function pointers. +@var{global} is true if the symbol may be affected by dynamic relocations. The macro should return a combination of the @code{DW_EH_PE_*} defines as found in @file{dwarf2.h}. @@ -2723,15 +2723,15 @@ If this macro is not defined, pointers will not be encoded but represented directly. @findex ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX -@item ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX(@var{FILE}, @var{ENCODING}, @var{SIZE}, @var{ADDR}, @var{DONE}) +@item 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 be defined if the target uses text-relative or data-relative encodings. -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} +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. @findex SMALL_STACK @@ -3047,7 +3047,7 @@ 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 PUSH_ARGS is nonzero, PUSH_ROUNDING must be defined too. +it. When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too. On some machines, the definition @findex PUSH_ROUNDING @@ -3157,7 +3157,7 @@ after the function returns. @var{fundecl} is a C variable whose value is a tree node that describes the function in question. Normally it is a node of type @code{FUNCTION_DECL} that describes the declaration of the function. -From this you can obtain the DECL_MACHINE_ATTRIBUTES of the function. +From this you can obtain the @code{DECL_MACHINE_ATTRIBUTES} of the function. @var{funtype} is a C variable whose value is a tree node that describes the function in question. Normally it is a node of type @@ -3316,7 +3316,7 @@ definition of this macro might be 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 -routine being called. When FUNCTION_ARG_CALLEE_COPIES is defined and is +routine being called. When @code{FUNCTION_ARG_CALLEE_COPIES} is defined and is 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; @@ -3733,7 +3733,7 @@ arguments. But usually, on such machines, nothing else has been pushed yet, because the function prologue itself does all the pushing.) This region is used on machines where an argument may be passed partly in registers and partly in memory, and, in some cases to support the -features in @file{varargs.h} and @file{stdarg.h}. +features in @code{} and @code{}. @item An area of memory used to save certain registers used by the function. @@ -3963,7 +3963,7 @@ that you know will result. The first word of this block is a flag which will be nonzero if the object module has already been initialized. So test this word first, and do not call @code{__bb_init_func} if the flag is -nonzero. BLOCK_OR_LABEL contains a unique number which may be used to +nonzero. @var{labelno} contains a unique number which may be used to generate a label as a branch destination when @code{__bb_init_func} will not be called. @@ -3982,14 +3982,14 @@ local_label: Output code to call the subroutine @code{__bb_init_trace_func} and pass two parameters to it. The first parameter is the same as for @code{__bb_init_func}. The second parameter is the number of the -first basic block of the function as given by BLOCK_OR_LABEL@. Note +first basic block of the function as given by @var{labelno}. Note that @code{__bb_init_trace_func} has to be called, even if the object module has been initialized already. Described in assembler language, the code to be output looks like: @example parameter1 <- LPBX0 -parameter2 <- BLOCK_OR_LABEL +parameter2 <- @var{labelno} call __bb_init_trace_func @end example @end table @@ -4024,7 +4024,7 @@ that you know will result. Described in assembler language, the code to be output looks like: @smallexample -inc (LPBX2+4*BLOCKNO) +inc (LPBX2+4*@var{blockno}) @end smallexample @vindex __bb @@ -4035,7 +4035,7 @@ call the function @code{__bb_trace_func}, which will increment the counter. @code{__bb} consists of two words. In the first word, the current -basic block number, as given by BLOCKNO, has to be stored. In +basic block number, as given by @var{blockno}, has to be stored. In the second word, the address of a block allocated in the object module has to be stored. The address is given by the label created with this statement: @@ -4046,7 +4046,7 @@ ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 0); Described in assembler language, the code to be output looks like: @example -move BLOCKNO -> (__bb) +move @var{blockno} -> (__bb) move LPBX0 -> (__bb+4) call __bb_trace_func @end example @@ -4151,13 +4151,13 @@ as the @code{sibcall} md pattern can not fail, or fall over to a @section Implementing the Varargs Macros @cindex varargs implementation -GCC comes with an implementation of @file{varargs.h} and -@file{stdarg.h} that work without change on machines that pass arguments +GCC comes with an implementation of @code{} and +@code{} that work without change on machines that pass arguments on the stack. Other machines require their own implementations of varargs, and the two machine independent header files must have conditionals to include it. -ISO @file{stdarg.h} differs from traditional @file{varargs.h} mainly in +ISO @code{} differs from traditional @code{} mainly in the calling convention for @code{va_start}. The traditional implementation takes just one argument, which is the variable in which to store the argument pointer. The ISO implementation of @@ -4448,12 +4448,12 @@ the instruction cache directly, you can define the following macro. @table @code @findex CLEAR_INSN_CACHE -@item CLEAR_INSN_CACHE (@var{BEG}, @var{END}) +@item 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 -INSN_CACHE_SIZE is defined, some generic code is generated to clear the +@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 +@code{asm} statements. Both @var{beg} and @var{end} are both pointer expressions. @end table @@ -4831,7 +4831,7 @@ reload register instead of two by reloading a sum of two pseudo registers into a register. On the other hand, for number of RISC processors offsets are limited so that often an intermediate address needs to be generated in order to address a stack slot. By defining -LEGITIMIZE_RELOAD_ADDRESS appropriately, the intermediate addresses +@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses generated for adjacent some stack slots can be made identical, and thus be shared. @@ -5062,7 +5062,8 @@ reversed safely. If no expansion is specified, this macro is defined as follows: @smallexample -#define REVERSE_CONDEXEC_PREDICATES_P (x, y) ((x) == reverse_condition (y)) +#define REVERSE_CONDEXEC_PREDICATES_P (x, y) \ + ((x) == reverse_condition (y)) @end smallexample @end table @@ -5544,7 +5545,7 @@ unique sections. @findex UNIQUE_SECTION @item UNIQUE_SECTION (@var{decl}, @var{reloc}) A C statement to build up a unique section name, expressed as a -STRING_CST node, and assign it to @samp{DECL_SECTION_NAME (@var{decl})}. +@code{STRING_CST} node, and assign it to @samp{DECL_SECTION_NAME (@var{decl})}. @var{reloc} indicates whether the initial value of @var{exp} requires link-time relocations. If you do not define this macro, GCC will use the symbol name prefixed by @samp{.} as the section name. Note - this @@ -6020,7 +6021,7 @@ the name, and a newline. This macro controls how the assembler definitions of uninitialized global variables are output. This macro exists to properly support languages like -@code{c++} which do not have @code{common} data. However, this macro currently +C++ which do not have @code{common} data. However, this macro currently 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 @@ -6335,7 +6336,7 @@ 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 SET_ASM_OP is defined, a default definition is provided which is +If @code{SET_ASM_OP} is defined, a default definition is provided which is correct for most systems. @findex ASM_OUTPUT_DEF_FROM_DECLS @@ -6356,7 +6357,7 @@ and @var{low} are already known by the assembler so that the difference resolves into a constant. @findex SET_ASM_OP -If SET_ASM_OP is defined, a default definition is provided which is +If @code{SET_ASM_OP} is defined, a default definition is provided which is correct for most systems. @findex ASM_OUTPUT_WEAK_ALIAS @@ -6366,7 +6367,7 @@ which defines (equates) the weak symbol @var{name} to have the value @var{value}. Define this macro if the target only supports weak aliases; define -ASM_OUTPUT_DEF instead if possible. +@code{ASM_OUTPUT_DEF} instead if possible. @findex OBJC_GEN_METHOD_LABEL @item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) @@ -6667,13 +6668,13 @@ Define this macro to a C string constant containing the name of the program which lists dynamic dependencies, like @code{"ldd"} under SunOS 4. @findex PARSE_LDD_OUTPUT -@item PARSE_LDD_OUTPUT (@var{PTR}) +@item 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 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}. +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 @@ -6912,7 +6913,7 @@ fprintf (@var{stream}, "\t.word L%d-L%d\n", 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 ADDR_DIFF_VEC; it is provided so that the +@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the mode and flags can be read. @findex ASM_OUTPUT_ADDR_VEC_ELT @@ -7015,12 +7016,12 @@ This macro need not be defined on most platforms. @findex DOESNT_NEED_UNWINDER @item DOESNT_NEED_UNWINDER A C expression that decides whether or not the current function needs to -have a function unwinder generated for it. See the file @code{except.c} +have a function unwinder generated for it. See the file @file{except.c} for details on when to define this, and how. @findex MASK_RETURN_ADDR @item MASK_RETURN_ADDR -An rtx used to mask the return address found via RETURN_ADDR_RTX, so +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. @findex DWARF2_UNWIND_INFO @@ -7033,11 +7034,11 @@ or @samp{OBJECT_FORMAT_ELF}), GCC will provide a default definition of 1. If this macro is defined to 1, the DWARF 2 unwinder will be the default -exception handling mechanism; otherwise, setjmp/longjmp will be used by +exception handling mechanism; otherwise, @code{setjmp}/@code{longjmp} will be used by default. If this macro is defined to anything, the DWARF 2 unwinder will be used -instead of inline unwinders and __unwind_function in the non-setjmp case. +instead of inline unwinders and @code{__unwind_function} in the non-@code{setjmp} case. @findex DWARF_CIE_DATA_ALIGNMENT @item DWARF_CIE_DATA_ALIGNMENT @@ -7060,7 +7061,7 @@ This describes commands for alignment. @findex LABEL_ALIGN_AFTER_BARRIER @item LABEL_ALIGN_AFTER_BARRIER (@var{label}) The alignment (log base 2) to put in front of @var{label}, which follows -a BARRIER@. +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 @@ -7081,16 +7082,16 @@ The maximum number of bytes to skip when applying @findex LOOP_ALIGN @item LOOP_ALIGN (@var{label}) The alignment (log base 2) to put in front of @var{label}, which follows -a NOTE_INSN_LOOP_BEG note. +a @code{NOTE_INSN_LOOP_BEG} note. 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. Unless it's necessary to inspect the @var{label} parameter, it is better -to set the variable @var{align_loops} in the target's +to set the variable @code{align_loops} in the target's @code{OVERRIDE_OPTIONS}. Otherwise, you should try to honour the user's -selection in @var{align_loops} in a @code{LOOP_ALIGN} implementation. +selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. @findex LOOP_ALIGN_MAX_SKIP @item LOOP_ALIGN_MAX_SKIP @@ -7100,13 +7101,13 @@ This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. @findex LABEL_ALIGN @item LABEL_ALIGN (@var{label}) The alignment (log base 2) to put in front of @var{label}. -If LABEL_ALIGN_AFTER_BARRIER / LOOP_ALIGN specify a different alignment, +If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, the maximum of the specified values is used. Unless it's necessary to inspect the @var{label} parameter, it is better -to set the variable @var{align_labels} in the target's +to set the variable @code{align_labels} in the target's @code{OVERRIDE_OPTIONS}. Otherwise, you should try to honour the user's -selection in @var{align_labels} in a @code{LABEL_ALIGN} implementation. +selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. @findex LABEL_ALIGN_MAX_SKIP @item LABEL_ALIGN_MAX_SKIP @@ -7800,7 +7801,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 MACHINE_DEPENDENT_REORG@. +or @code{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 @@ -7828,8 +7829,8 @@ switch is needed / supplied. @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 -NUM_MODES_FOR_MODE_SWITCHING, to denote the mode that @var{entity} must -be switched into prior to the execution of INSN@. +@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must +be switched into prior to the execution of @var{insn}. @findex NORMAL_MODE @item NORMAL_MODE (@var{entity}) @@ -7839,12 +7840,12 @@ mode switching. It should evaluate to an integer, which is a mode that @findex MODE_PRIORITY_TO_MODE @item MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) -This macro specifies the order in which modes for ENTITY are processed. -0 is the highest priority, NUM_MODES_FOR_MODE_SWITCHING[ENTITY] - 1 the +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 ENTITY@. For any fixed @var{entity}, @code{mode_priority_to_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}] @minus{} 1 . +@code{num_modes_for_mode_switching[@var{entity}] - 1}. @findex EMIT_MODE_SET @item EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) @@ -7885,7 +7886,7 @@ thus speeding up the compiler. The most important predicates to include in the list specified by this macro are those used in the most insn patterns. -For each predicate function named in @var{PREDICATE_CODES}, a +For each predicate function named in @code{PREDICATE_CODES}, a declaration will be generated in @file{insn-codes.h}. @item SPECIAL_MODE_PREDICATES @@ -8260,7 +8261,7 @@ other language compilers for that matter. Thus if @code{c_lex} is going to be called from target-specific code, it must only be done so when building the C and C++ compilers. This can be done by defining the variables @code{c_target_objs} and @code{cxx_target_objs} in the -target entry in the @code{config.gcc} file. These variables should name +target entry in the @file{config.gcc} file. These variables should name the target-specific, language-specific object file which contains the code that uses @code{c_lex}. Note it will also be necessary to add a rule to the makefile fragment pointed to by @code{tmake_file} that shows @@ -8298,8 +8299,8 @@ of specifically named weak labels, optionally with a value. @findex pragma @item 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,)} and @samp{#pragma -pack(pop)}. The pack(push,) pragma specifies the maximum alignment +style pragmas @samp{#pragma pack(push,@var{n})} and @samp{#pragma +pack(pop)}. The @samp{pack(push,@var{n})} pragma specifies the maximum alignment (in bytes) of fields within a structure, in much the same way as the @samp{__aligned__} and @samp{__packed__} @code{__attribute__}s do. A pack value of zero resets the behaviour to the default. Successive @@ -8473,8 +8474,8 @@ without user intervention. For instance, under Microsoft Windows symbols must be explicitly imported from shared libraries (DLLs). @findex MD_ASM_CLOBBERS -@item MD_ASM_CLOBBERS -A C statement that adds to @var{CLOBBERS} @code{STRING_CST} trees for +@item 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. @findex ISSUE_RATE -- 2.30.2