2003-05-11 Paul A. Crable * doc/invoke.texi: Re-arranged option lists for M68h1x, VAX, and ARM. Fixes to spelling, grammar, and diction. Re-arranged -mcmodel, -mcode-model, and -msdata options. --- invoke.texi.orig 2003-05-13 10:22:56.000000000 -0400 +++ invoke.texi 2003-05-13 11:37:20.000000000 -0400 @@ -329,7 +329,7 @@ @emph{M68hc1x Options} @gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol --mauto-incdec -minmax -mlong-calls -mshort @gol +-mauto-incdec -minmax -nominmax -mlong-calls -mshort @gol -msoft-reg-count=@var{count}} @emph{VAX Options} @@ -340,14 +340,18 @@ -mtune=@var{cpu-type} @gol -mcmodel=@var{code-model} @gol -m32 -m64 @gol --mapp-regs -mbroken-saverestore -mcypress @gol --mfaster-structs -mflat @gol --mfpu -mhard-float -mhard-quad-float @gol --mimpure-text -mlive-g0 -mno-app-regs @gol --mno-faster-structs -mno-flat -mno-fpu @gol --mno-impure-text -mno-stack-bias -mno-unaligned-doubles @gol --msoft-float -msoft-quad-float -msparclite -mstack-bias @gol --msupersparc -munaligned-doubles -mv8} +-mapp-regs -mno-app-regs @gol +-mbroken-saverestore -mcypress @gol +-mfaster-structs -mno-faster-structs @gol +-mflat -mno-flat @gol +-mfpu -mno-fpu @gol +-mhard-float -mhard-quad-float @gol +-mimpure-text -mno-impure-text @gol +-mlive-g0 -msoft-float -msoft-quad-float -msparclite @gol +-mstack-bias -mno-stack-bias @gol +-msupersparc @gol +-munaligned-doubles -mno-unaligned-doubles @gol +-mv8} @emph{ARM Options} @gccoptlist{-mapcs-frame -mno-apcs-frame @gol @@ -419,8 +423,9 @@ -mabi=spe -mabi=no-spe @gol -misel=yes -misel=no @gol -mprototype -mno-prototype @gol --msim -mmvme -mads -myellowknife -memb -msdata @gol --msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread} +-msim -mmvme -mads -myellowknife -memb @gol +-msdata=@var{opt} -no-msdata @gol +-mvxworks -mwindiss -G @var{num} -pthread} @emph{Darwin Options} @gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol @@ -5613,13 +5618,16 @@ @itemx -nominmax @opindex minmax @opindex mnominmax -Enable the use of 68HC12 min and max instructions. +Enable (@option{-minmax}) or prevent (@option{-nominmax}) the use of 68HC12 +min and max instructions. @item -mlong-calls @itemx -mno-long-calls @opindex mlong-calls @opindex mno-long-calls -Treat all calls as being far away (near). If calls are assumed to be +Treat all calls as being far away (@option{-mlong-calls}) or generate mixed +calls as the situation warrants (@option{-mno-long-calls}). +If calls are assumed to be far away, the compiler will use the @code{call} instruction to call a function and the @code{rtc} instruction for returning. @@ -5643,16 +5651,14 @@ These @samp{-m} options are defined for the VAX: @table @gcctabopt -@item -munix -@opindex munix -Do not output certain jump instructions (@code{aobleq} and so on) -that the Unix assembler for the VAX cannot handle across long -ranges. - @item -mgnu +@itemx -munix @opindex mgnu -Do output those jump instructions, on the assumption that you -will assemble with the GNU assembler. +@opindex munix +Output (@option{-mgnu}) or suppress (@option{-munix}) +certain jump instructions (@code{aobleq} and so on) +that the Unix assembler for the VAX cannot handle across long +ranges. Use @option{-mgnu} if you will assemble with the GNU assembler. @item -mg @opindex mg @@ -5714,7 +5720,7 @@ floating point instructions. The functions called are those specified in the SPARC ABI@. This is the default. -As of this writing, there are no sparc implementations that have hardware +As of this writing, there are no SPARC implementations that have hardware support for the quad-word floating point instructions. They all invoke a trap handler for one of these instructions, and then the trap handler emulates the effect of the instruction. Because of the trap handler overhead, @@ -5791,7 +5797,7 @@ Cypress CY7C602 chip, as used in the SPARCStation/SPARCServer 3xx series. This is also appropriate for the older SPARCStation 1, 2, IPX etc. -With @option{-msupersparc} the compiler optimizes code for the SuperSPARC cpu, as +With @option{-msupersparc} the compiler optimizes code for the SuperSPARC CPU, as used in the SPARCStation 10, 1000 and 2000 series. This flag also enables use of the full SPARC v8 instruction set. @@ -5830,15 +5836,15 @@ The same values for @option{-mcpu=@var{cpu_type}} can be used for @option{-mtune=@var{cpu_type}}, but the only useful values are those -that select a particular cpu implementation. Those are @samp{cypress}, +that select a particular CPU implementation. Those are @samp{cypress}, @samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934}, @samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc}, and @samp{ultrasparc3}. @end table -These @samp{-m} switches are supported in addition to the above -on the SPARCLET processor. +These @samp{-m} switches are supported in addition to the normal SPARC +options on the SPARCLET processor. @table @gcctabopt @item -mlittle-endian @@ -5863,8 +5869,8 @@ handlers. @end table -These @samp{-m} switches are supported in addition to the above -on SPARC V9 processors in 64-bit environments. +These @samp{-m} switches are supported in addition to the normal SPAC +options on SPARC V9 processors in 64-bit environments. @table @gcctabopt @item -mlittle-endian @@ -5880,33 +5886,40 @@ The 64-bit environment sets int to 32 bits and long and pointer to 64 bits. -@item -mcmodel=medlow +@item -mcmodel=@var{model_type} +@opindex mcmodel +Specify the code model to use. +@var{model_type} may take one of the following values: + +@table @gcctabopt +@item medlow @opindex mcmodel=medlow Generate code for the Medium/Low code model: the program must be linked in the low 32 bits of the address space. Pointers are 64 bits. Programs can be statically or dynamically linked. -@item -mcmodel=medmid +@item medmid @opindex mcmodel=medmid Generate code for the Medium/Middle code model: the program must be linked in the low 44 bits of the address space, the text segment must be less than 2G bytes, and data segment must be within 2G of the text segment. Pointers are 64 bits. -@item -mcmodel=medany +@item medany @opindex mcmodel=medany Generate code for the Medium/Anywhere code model: the program may be linked anywhere in the address space, the text segment must be less than 2G bytes, and data segment must be within 2G of the text segment. Pointers are 64 bits. -@item -mcmodel=embmedany +@item embmedany @opindex mcmodel=embmedany Generate code for the Medium/Anywhere code model for embedded systems: assume a 32-bit text and a 32-bit data segment, both starting anywhere (determined at link time). Register %g4 points to the base of the data segment. Pointers are still 64 bits. Programs are statically linked, PIC is not supported. +@end table @item -mstack-bias @itemx -mno-stack-bias @@ -5926,7 +5939,9 @@ architectures: @table @gcctabopt -@item -mapcs-frame +@item -mapcs +@itemx -mapcs-frame +@opindex mapcs @opindex mapcs-frame Generate a stack frame that is compliant with the ARM Procedure Call Standard for all functions, even if this is not strictly necessary for @@ -5934,10 +5949,6 @@ with this option will cause the stack frames not to be generated for leaf functions. The default is @option{-mno-apcs-frame}. -@item -mapcs -@opindex mapcs -This is a synonym for @option{-mapcs-frame}. - @item -mapcs-26 @opindex mapcs-26 Generate code for a processor running with a 26-bit program counter, @@ -6099,14 +6110,12 @@ @itemx -mtune=@var{name} @opindex mtune -This option is very similar to the @option{-mcpu=} option, except that -instead of specifying the actual target processor type, and hence -restricting which instructions can be used, it specifies that GCC should -tune the performance of the code as if the target were of the type +Tune the performance of the code as if the target were of the type specified in this option, but still choosing the instructions that it -will generate based on the cpu specified by a @option{-mcpu=} option. +will generate based on the CPU specified by a @option{-mcpu=} option. For some ARM implementations better performance can be obtained by using this option. +@option{-mtune=} takes the same arguments as @option{-mcpu=}. @item -march=@var{name} @opindex march @@ -6127,8 +6136,8 @@ @item -mstructure-size-boundary=@var{n} @opindex mstructure-size-boundary -The size of all structures and unions will be rounded up to a multiple -of the number of bits set by this option. Permissible values are 8 and +Round up the size of all structures and unions to a multiple +of @var{n} bits, as set by this option. Permissible values are 8 and 32. The default value varies for different toolchains. For the COFF targeted toolchain the default value is 8. Specifying the larger number can produce faster, more efficient code, but can also increase the size @@ -6247,7 +6256,7 @@ @subsection MN10200 Options @cindex MN10200 options -These @option{-m} options are defined for Matsushita MN10200 architectures: +This @option{-m} option is defined for Matsushita MN10200 architectures: @table @gcctabopt @item -mrelax @@ -6267,23 +6276,20 @@ @table @gcctabopt @item -mmult-bug +@itemx -mno-mult-bug @opindex mmult-bug -Generate code to avoid bugs in the multiply instructions for the MN10300 -processors. This is the default. - -@item -mno-mult-bug @opindex mno-mult-bug -Do not generate code to avoid bugs in the multiply instructions for the -MN10300 processors. - -@item -mam33 -@opindex mam33 -Generate code which uses features specific to the AM33 processor. +Generate (@option{-mmult-bug}) or do not generate (@option{-mno-mult-bug}) +code to avoid bugs in the multiply instructions for the MN10300 +processors. @option{-mmult-bug} is the default. @item -mno-am33 +@itemx -mam33 @opindex mno-am33 -Do not generate code which uses features specific to the AM33 processor. This -is the default. +@opindex mam33 +Generate (@option{-mam33}) or do not generate (@option{-mno-am33}) code +which uses features specific to the AM33 processor. @option{-mno-am33} is +the default. @item -mno-crt0 @opindex mno-crt0 @@ -6314,7 +6320,13 @@ @opindex m32r Generate code for the M32R@. This is the default. -@item -mcode-model=small +@item -mcode-model=@var{model_type} +@opindex mcode-model +Specify the memory model to use. +@var{model_type} can take one of the following values: + +@table @gcctabopt +@item small @opindex mcode-model=small Assume all objects live in the lower 16MB of memory (so that their addresses can be loaded with the @code{ld24} instruction), and assume all subroutines @@ -6324,21 +6336,28 @@ The addressability of a particular object can be set with the @code{model} attribute. -@item -mcode-model=medium +@item medium @opindex mcode-model=medium Assume objects may be anywhere in the 32-bit address space (the compiler will generate @code{seth/add3} instructions to load their addresses), and assume all subroutines are reachable with the @code{bl} instruction. -@item -mcode-model=large +@item large @opindex mcode-model=large Assume objects may be anywhere in the 32-bit address space (the compiler will generate @code{seth/add3} instructions to load their addresses), and assume subroutines may not be reachable with the @code{bl} instruction (the compiler will generate the much slower @code{seth/add3/jl} instruction sequence). +@end table + +@item -msdata=@var{area} +@opindex msdata +Specify whether to use the small data area. +@var{area} can take one of the following values: -@item -msdata=none +@table @gcctabopt +@item none @opindex msdata=none Disable use of the small data area. Variables will be put into one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the @@ -6349,15 +6368,16 @@ Objects may be explicitly put in the small data area with the @code{section} attribute using one of these sections. -@item -msdata=sdata +@item sdata @opindex msdata=sdata Put small global and static data in the small data area, but do not generate special code to reference them. -@item -msdata=use +@item use @opindex msdata=use Put small global and static data in the small data area, and generate special instructions to reference them. +@end table @item -G @var{num} @opindex G @@ -7111,7 +7131,22 @@ small data area. The @option{-meabi} option is on by default if you configured GCC using one of the @samp{powerpc*-*-eabi*} options. -@item -msdata=eabi +@item -msdata=@var{area} +@itemx -msdata +@opindex msdata +@option{-msdata} is a synonym for @option{-msdata=default}. + +Specify where GCC should be small initalized global and static data. +@var{area} may be one of the following values: + +@table @gcctabopt +@item default +@opindex msdata=default +On System V.4 and embedded PowerPC systems, if @option{-meabi} is used, +compile code the same as @option{-msdata=eabi}, otherwise compile code the +same as @option{-msdata=sysv}. + +@item eabi @opindex msdata=eabi On System V.4 and embedded PowerPC systems, put small initialized @code{const} global and static data in the @samp{.sdata2} section, which @@ -7123,7 +7158,7 @@ incompatible with the @option{-mrelocatable} option. The @option{-msdata=eabi} option also sets the @option{-memb} option. -@item -msdata=sysv +@item sysv @opindex msdata=sysv On System V.4 and embedded PowerPC systems, put small global and static data in the @samp{.sdata} section, which is pointed to by register @@ -7132,29 +7167,24 @@ The @option{-msdata=sysv} option is incompatible with the @option{-mrelocatable} option. -@item -msdata=default -@itemx -msdata -@opindex msdata=default -@opindex msdata -On System V.4 and embedded PowerPC systems, if @option{-meabi} is used, -compile code the same as @option{-msdata=eabi}, otherwise compile code the -same as @option{-msdata=sysv}. - -@item -msdata-data -@opindex msdata-data +@item data +@opindex msdata=data On System V.4 and embedded PowerPC systems, put small global and static data in the @samp{.sdata} section. Put small uninitialized global and static data in the @samp{.sbss} section. Do not use register @code{r13} to address small data however. This is the default behavior unless other @option{-msdata} options are used. -@item -msdata=none -@itemx -mno-sdata +@item none @opindex msdata=none -@opindex mno-sdata On embedded PowerPC systems, put all initialized global and static data in the @samp{.data} section, and all uninitialized data in the @samp{.bss} section. +@end table + +@item -mno-sdata +@opindex mno-sdata +@option{-mno-sdata} is a synonym for @option{-msdata=none} @item -G @var{num} @opindex G @@ -7880,7 +7910,7 @@ @code{sqrt} instructions for the 387. Specify this option to avoid generating those instructions. This option is the default on FreeBSD, OpenBSD and NetBSD@. This option is overridden when @option{-march} -indicates that the target cpu will always have an FPU and so the +indicates that the target CPU will always have an FPU and so the instruction will not need emulation. As of revision 2.6.1, these instructions are not generated unless you also use the @option{-funsafe-math-optimizations} switch. @@ -8084,32 +8114,39 @@ and therefore can be used for temporary data without adjusting the stack pointer. The flag @option{-mno-red-zone} disables this red zone. -@item -mcmodel=small +@table @gcctabopt +@item -mcmodel=@var{model_type} +@opindex mcmodel +Specify the code model to use. +@var{model_type} may take one of the following values: + +@item small @opindex mcmodel=small Generate code for the small code model: the program and its symbols must be linked in the lower 2 GB of the address space. Pointers are 64 bits. Programs can be statically or dynamically linked. This is the default code model. -@item -mcmodel=kernel +@item kernel @opindex mcmodel=kernel Generate code for the kernel code model. The kernel runs in the negative 2 GB of the address space. This model has to be used for Linux kernel code. -@item -mcmodel=medium +@item medium @opindex mcmodel=medium Generate code for the medium model: The program is linked in the lower 2 GB of the address space but symbols can be located anywhere in the address space. Programs can be statically or dynamically linked, but building of shared libraries are not supported with the medium model. -@item -mcmodel=large +@item large @opindex mcmodel=large Generate code for the large model: This model makes no assumptions about addresses and sizes of sections. Currently GCC does not implement this model. @end table +@end table @node HPPA Options @subsection HPPA Options @@ -9180,10 +9217,10 @@ @item -mmangle-cpu @opindex mmangle-cpu -Prepend the name of the cpu to all public symbol names. +Prepend the name of the CPU to all public symbol names. In multiple-processor systems, there are many ARC variants with different instruction and register set characteristics. This flag prevents code -compiled for one cpu to be linked with code compiled for another. +compiled for one CPU to be linked with code compiled for another. No facility exists for handling variants that are ``almost identical''. This is an all or nothing option. @@ -9246,7 +9283,7 @@ @opindex m32381 Generate output containing 32381 instructions for floating point. This also implies @option{-m32081}. The 32381 is only compatible with the 32332 -and 32532 cpus. This is the default for the pc532-netbsd configuration. +and 32532 CPUs. This is the default for the pc532-netbsd configuration. @item -mmulti-add @opindex mmulti-add