Patch to revamp MIPS documentation

Richard Sandiford rsandifo@redhat.com
Sun Jan 4 20:15:00 GMT 2004


While working on some -mexplicit-relocs stuff, I noticed the MIPS
documentation is very out of date.  Here's an attempt to improve
things a bit.

First of all, the patch removes the documentation for:

    -mabi=eabi
    -mips-tfile
    -m4650
    -mfix7000
    -(m)no-crt0
        These options aren't supported any more.

    -mabi-fake-default
        This option is only understood by one configuration
        (mips64*-linux-gnu) and it's just an internal device to beat
        the multilib machinery.  I don't think it belongs in user
        documentation.

    -mgas
    -mmips-as
        Although these options are still understood, I don't think they
        should be documented:

        - -mmips-as is something of a misnomer these days: I think the
          only non-GAS assemblers we support are the SGI ones.

        - The choice between SGI and GNU assemblers is made at configure
          time, not invocation time, so -mgas and -mmips-as don't really
          do what you'd want.

        - The current documentation:
        
             @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. [...]

          ...is hopelessly out of date ;)

The patch also tweaks the entries for several other options.
I hope the new wording is an improvement...

Finally, the order of the options seemed a bit hapzard.  I tried
to rearrange them as follows:

    - endianness options
    - architecture options
    - ABI options
    - everything else (optimisation options, etc.)

but not all options fall neatly into these categories, so the
new order isn't perfect either.

I'll add -mexplicit-relocs in a separate patch.

Tested with "make info".  "make dvi" choked on doc/md.texi for reasons
I don't fully understand, but it did the same thing before my patch.
Removing the final @ifset conditional worked around that and the
output looked OK as far as the MIPS options go.  OK to install?

Richard


	* doc/invoke.texi: Revamp documentation of MIPS options.  Remove
	-mabi=eabi, -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.

Index: doc/invoke.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/invoke.texi,v
retrieving revision 1.379
diff -c -p -F^\([(a-zA-Z0-9_]\|#define\) -r1.379 invoke.texi
*** doc/invoke.texi	2 Jan 2004 10:58:42 -0000	1.379
--- doc/invoke.texi	4 Jan 2004 20:13:10 -0000
*************** in the following sections.
*** 484,506 ****
  -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}
  
  @emph{i386 and x86-64 Options}
  @gccoptlist{-mtune=@var{cpu-type}  -march=@var{cpu-type} @gol
--- 484,503 ----
  -mminimum-fp-blocks  -mnohc-struct-return}
  
  @emph{MIPS Options}
! @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
*************** option @option{-mhc-struct-return}.
*** 8026,8035 ****
  @subsection MIPS Options
  @cindex MIPS options
  
- These @samp{-m} options are defined for the MIPS family of computers:
- 
  @table @gcctabopt
  
  @item -march=@var{arch}
  @opindex march
  Generate code that will run on @var{arch}, which can be the name of a
--- 8023,8039 ----
  @subsection MIPS Options
  @cindex MIPS options
  
  @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
*************** Equivalent to @samp{-march=mips32r2}.
*** 8114,8303 ****
  @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 -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
  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.
  
  @item -mxgot
  @itemx -mno-xgot
  @opindex mxgot
  @opindex mno-xgot
! Lift (or 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.
--- 8118,8157 ----
  @opindex mips64
  Equivalent to @samp{-march=mips64}.
  
! @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
  @opindex mabi=32
  @opindex mabi=o64
  @opindex mabi=n32
  @opindex mabi=64
  @opindex mabi=eabi
  Generate code for the given ABI@.
  
! 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.
*************** file accesses more than 64k's worth of G
*** 8322,8345 ****
  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@.
  
  @item -membedded-data
  @itemx -mno-embedded-data
--- 8176,8258 ----
  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.
! 
! @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
*************** when executing, and thus may be preferre
*** 8354,8434 ****
  @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.
  
! @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.
  
! @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 -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.
  
  @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
  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
--- 8267,8349 ----
  @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
! 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
! Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
! instructions, as provided by the R4650 ISA.
! 
! @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}.
! 
! 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 -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



More information about the Gcc-patches mailing list