invoke.texi: Revamp documentation of MIPS options.

	* doc/invoke.texi: Revamp documentation of MIPS options.  Remove
	-mabi=meabi, -mabi-fake-default, -mmips-as, -mgas, -mmips-tfile,
	-m4650, -mfix7000 and -(m)no-crt0.  Put endianness options first,
	then architecture options, then ABI options.  General rewording.

From-SVN: r75396

2 files changed, 170 insertions, 248 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index f37704c..1ccaf2a 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,10 @@
+2004-01-04  Richard Sandiford  <rsandifo@redhat.com>
+
+	* doc/invoke.texi: Revamp documentation of MIPS options.  Remove
+	-mabi=meabi, -mabi-fake-default, -mmips-as, -mgas, -mmips-tfile,
+	-m4650, -mfix7000 and -(m)no-crt0.  Put endianness options first,
+	then architecture options, then ABI options.  General rewording.
+
 2004-01-04  Joseph S. Myers  <jsm@polyomino.org.uk>
 
 	PR c/3414
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 96521e5..b875145 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -484,23 +484,20 @@ in the following sections.
 -mminimum-fp-blocks  -mnohc-struct-return}
 
 @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  -mhard-float  -mint64  -mips1 @gol
--mips2  -mips3  -mips4  -mips32  -mips32r2  -mips64 @gol
--mlong64  -mlong32  -mlong-calls  -mmemcpy @gol
--mmips-as  -mmips-tfile  -mno-abicalls  -mxgot @gol
--mno-embedded-data  -mno-uninit-const-in-rodata @gol
--mno-embedded-pic  -mno-long-calls @gol
--mno-memcpy  -mno-mips-tfile  -mno-rnames @gol
--mrnames  -msoft-float @gol
--m4650  -msingle-float  -mmad @gol
--EL  -EB  -G @var{num}  -nocpp @gol
--mabi=32  -mabi=n32  -mabi=64  -mabi=eabi  -mabi-fake-default @gol
--mfix7000  -mfix-sb1  -mno-fix-sb1 @gol
--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  -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{-mtune=@var{cpu-type}  -march=@var{cpu-type} @gol
@@ -8026,10 +8023,17 @@ option @option{-mhc-struct-return}.
 @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
@@ -8114,190 +8118,40 @@ Equivalent to @samp{-march=mips32r2}.
 @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 -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 -mgp32
-@opindex mgp32
-Assume that general purpose registers are 32 bits wide.
-
-@item -mgp64
-@opindex mgp64
-Assume that general purpose registers are 64 bits wide.
-
-@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.
-
-@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.
-
-@item -mlong32
-@opindex mlong32
-Force long, 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.
+@item -mips16
+@itemx -mno-mips16
+@opindex mips16
+@opindex mno-mips16
+Use (do not use) the MIPS16 ISA.
 
 @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@.
 
-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
+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 -mabi-fake-default
-@opindex mabi-fake-default
-You don't want to know what this option does.  No, really.  I mean
-it.  Move on to the next option.
-
-What?  You're still here?  Oh, well@enddots{}  Ok, here's the deal.  GCC
-wants the default set of options to get the root of the multilib tree,
-and the shared library SONAMEs without any multilib-indicating
-suffixes.  This is not convenience for @samp{mips64-linux-gnu}, since
-we want to default to the N32 ABI, while still being binary-compatible
-with @samp{mips-linux-gnu} if you stick to the O32 ABI@.  Being
-binary-compatible means shared libraries should have the same SONAMEs,
-and libraries should live in the same location.  Having O32 libraries
-in a sub-directory named say @file{o32} is not acceptable.
-
-So we trick GCC into believing that O32 is the default ABI, except
-that we override the default with some internal command-line
-processing magic.  Problem is, if we stopped at that, and you then
-created a multilib-aware package that used the output of @command{gcc
--print-multi-lib} to decide which multilibs to build, and how, and
-you'd find yourself in an awkward situation when you found out that
-some of the options listed ended up mapping to the same multilib, and
-none of your libraries was actually built for the multilib that
-@option{-print-multi-lib} claims to be the default.  So we added this
-option that disables the default switcher, falling back to GCC's
-original notion of the default library.  Confused yet?
-
-For short: don't ever use this option, unless you find it in the list
-of additional options to be used when building for multilibs, in the
-output of @option{gcc -print-multi-lib}.
-
-@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 -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 -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.
-
-@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 -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.
+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 (or do not lift) the usual restrictions on the size of the global
+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.
@@ -8322,24 +8176,83 @@ 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 -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 -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@.
+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.
+
+@item -mgp64
+@opindex mgp64
+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 @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 @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 @code{long}, @code{int}, and pointer types to be 32 bits wide.
+
+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 -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.
+
+All modules should be compiled with the same @option{-G @var{num}}
+value.
 
 @item -membedded-data
 @itemx -mno-embedded-data
@@ -8354,71 +8267,77 @@ when executing, and thus may be preferred for some embedded systems.
 @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.
+Put uninitialized @code{const} variables in the read-only data section.
+This option is only meaningful in conjunction with @option{-membedded-data}.
 
-@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.
+@item -msplit-addresses
+@itemx -mno-split-addresses
+@opindex msplit-addresses
+@opindex mno-split-addresses
+Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
+relocation operators.
+
+@item -mrnames
+@itemx -mno-rnames
+@opindex mrnames
+@opindex mno-rnames
+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
+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
+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.
+
+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.
+Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
+instructions, as provided by the R4650 ISA.
 
-@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.
-
-@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 -mfix-sb1
 @itemx -mno-fix-sb1
 @opindex mfix-sb1
@@ -8426,10 +8345,6 @@ 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 -no-crt0
-@opindex no-crt0
-Do not include the default crt0.
-
 @item -mflush-func=@var{func}
 @itemx -mno-flush-func
 @opindex mflush-func