[Bug-gnupress] Modifications to gcc.006.txt (#4)

[Paul A. Crable]

Remove section 3.17.5, ARM Options, in its entirety, and
substitute the following:

-------------------------------------

3.17.5 ARM Options

These `-m' options are defined for Advanced RISC Machines
(ARM) architectures:

-mapcs
-mapcs-frame

Generate a stack frame that complies with the ARM
Procedure Call Standard for all functions, even if doing
so is not strictly necessary. Specifying `-fomit-frame-
pointer' with this option will cause the stack frames not
to be generated for leaf functions.  If this option is
omitted, then ??????????????????.

-mapcs-26
-mapcs-32

Generate code for a processor running with a 26­bit
program counter (-mapcs-26) or a 32-bit program counter (-
mapcs-32).  -mapcs-26 replaces the `-m2' and `-m3' options
of previous releases of the compiler, and generates output
conforming to the function calling standards for the APCS
26­bit option.   -mapcs-32 replaces the `-m6' option of
previous releases of the compiler, and generates output
conformingto the function calling standards for the APCS
32­bit option.  If neither of these options is specified,
then ??????????????????.

-mthumb-interwork

Generate code which supports calling between the ARM and
Thumb instruction sets. Without this option, the two
instruction sets cannot be used together reliably.  This
option produces a slightly larger program.

-mno-sched-prolog

Prevent the reordering of instructions in the function
prolog, or the merging of those instruction with the
instructions in the function's body. This means that all
functions will start with a recognizable set of
instructions (or in reality one from a small number of
different function prologues), and this information can be
used to locate the start of functions inside an executable
piece of code.  If this option is omitted, the
instructions may be reorderd.

-mhard-float
-msoft-float

Generate output containing hardware floating point
instructions (-mhard-float) or library calls to floating
point processing software.  `-msoft-float' changes the
calling convention; therefore, you must compile all
modules of a program with this option. In particular, you
must compile `libgcc.a', the library that comes with GCC,
with `-msoft-float'.  The default value is ???????????.

Warning: If -soft-float is specified, be aware that the
requisite libraries are not available for all ARM targets.
Normally the facilities of the machine's usual C compiler
are used, but this cannot be done directly in
cross­compilation. You must make your own arrangements to
provide suitable library functions for cross-compilation.

-mlittle-endian
-mbig-endian

Generate code for a processor running in little­endian (-
mlittle-endian) or big­endian (-mbig-endian) mode.  The
default is -mlittle-endian.

-mwords-little-endian

Generate code for a little­endian word order but a
big­endian byte order. That is, a byte order of the form
`32107654'.  This option is only available if -mbig-endian
is specified.  Use this option only if you require
compatibility with code for big­endian ARM processors
generated by versions of the compiler prior to 2.8.

-malignment-traps
-mno-alignment-traps

Generate code that will not trap if the MMU has alignment
traps enabled (-malignment-traps) or generate code that
assumes that the MMU will not trap unaligned accesses (-
mno-alignment-traps). On ARM architectures prior to ARMv4,
there were no instructions to access half­word objects
stored in memory. When reading from memory, however, a
feature of the ARM architecture allows a word load to be
used, even if the address is unaligned, and the processor
core will rotate the data as it is being loaded.

-malignment-traps tells the compiler that such misaligned
accesses will cause a MMU trap and that it should instead
synthesize the access as a series of byte accesses. The
compiler can still use word accesses to load half­word
data if it knows that the address is aligned to a word
boundary. This option is ignored when compiling for ARM
architecture 4 or later, since these processors have
instructions to directly access half­word objects in
memory.

Setting -mnoalignment-traps causes GCC to generate code
that assumes that the MMU will not trap unaligned
accesses. This produces better code when the target
instruction set does not have half­word memory operations
(i.e. implementations prior to ARMv4). Note that you
cannot use this option to access unaligned word objects,
since the processor will only fetch one 32­bit aligned
object from memory.

The default setting for most targets is `-mno-alignment-
traps', since this produces better code when there are no
half­word memory in­ structions available.

???--"most" is a little ambiguous; we should list the
default value for every target.

-mshort-load-bytes
-mno-short-load-words

These are deprecated aliases for `-malignment-traps'.

-mno-short-load-bytes
-mshort-load-words

These are deprecated aliases for `-mno-alignment-traps'.

-mcpu=name

Generate instructions for target type name.  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', and `xscale'.  If this option is
omitted, then instruction will be generated for
??????????.

-mtune=name

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 `-mcpu=' option. For some ARM
implementations better performance can be obtained by
using this option.  -mtune takes the same arguments as -
mcpu.

-march=name

Generate assembly code for target architecture name.  This
option can be used in conjunction with or instead of the
`-mcpu=' option. Permissible names are: `armv2', `armv2a',
`armv3', `armv3m', `armv4', `armv4t', `armv5', `armv5t',
`armv5te'.  If this option is omitted, then ??????????.

-mfpe=emulation_number
-mfp=emulation_number

Generate output for floating point emulation of type
emulation_number. Permissible values are 2 and 3. `-mfp='
is a synonym for `-mfpe=', for compatibility with older
versions of GCC.  The default value is ??????????????.

-mstructure-size-boundary=number_of_bits

Round the size of all structures and unions up to a
multiple of number_of_bits. Permissible values are 8 and
32. The default value varies for different toolchains. For
the COFF targeted toolchain the default value is 8.  The
default value for other toolchains is ??????????????.
Specifying the larger number can produce faster, more
efficient code, but can also increase the size of the
program.  Combining code compiled with two different
values can produce unpredictable results.

-mabort-on-noreturn

Generate a call to the function abort at the end of a
noreturn function.  Abort will be executed if the function
tries to return.

-mlong-calls
-mno-long-calls

Generate (-mlong-calls) or do not generate (-mno-long-
calls) function calls by loading the address of the
function into a register and then performing a subroutine
call on this register. This switch is needed if the target
function will lie outside of the 64 megabyte addressing
range of the offset-based version of the subroutine call
instruction.  -mno-long-calls is the default value.

Even if this switch is enabled, not all function calls
will be turned into long calls. The heuristic is that
static functions, functions which have the `short-call'
attribute, functions that are inside the scope of a
`#pragma no_long_calls' directive, and functions whose
definitions have already been compiled within the current
compilation unit, will not be turned into long calls.  The
exception to this rule is that weak function definitions,
functions with the `long-call' attribute or the `section'
attribute, and functions that are within the scope of a
`#pragma long_calls' directive, will always be turned into
long calls.

Specifying `-mno-long-calls' will restore the default
behavior, as will placing the function calls within the
scope of a `#pragma long_calls_off' directive.  Note hat
these switches have no effect on how the compiler
generates code to handle function calls via function
pointers.

-mnop-fun-dllimport

Disable support for the dllimport attribute.

-msingle-pic-base

Treat the register used for PIC addressing as read­only,
rather than loading it in the prologue for each function.
The run­time system will then be responsible for
initializing this register with an appropriate value
before execution begins.

-mpic-register=reg

Specify the register to be used for PIC addressing. The
default is R10 unless stack­checking is enabled, when R9
is used.  The permitted values are ???? to ?????.

-mpoke-function-name

Write the name of each function into the text section,
directly preced­ ing the function prologue. The generated
code is similar to this: t0

        .ascii "arm_poke_function_name", 0
        .align
        t1
        .word 0xff000000 + (t1 - t0)
        arm_poke_function_name
        mov ip, sp
        stmfd sp!, {fp, ip, lr, pc}
        sub fp, ip, #4

When performing a stack backtrace, code can inspect the
value of pc stored at fp + 0. If the trace function then
looks at location pc -12 and the top 8 bits are set, then
you know that there is a function name embedded
immediately preceding this location and has length ((pc[-
3]) & 0xff000000).

-mthumb

Generate code for the 16­bit Thumb instruction set.
Normally GCC uses the 32­bit ARM instruction set.

-mtpcs-frame

Generate a stack frame that complies with the Thumb
Procedure Call Standard for all non­leaf functions. (A
leaf function is one that does not call any other
functions.)

-mtpcs-leaf-frame

Generate a stack frame that complies with the Thumb
Procedure Call Standard for all leaf functions. (A leaf
function is one that does not call any other functions).

-mcallee-super-interworking

Provide all externally visible functions in the file being
compiled an ARM instruction set header which switches to
Thumb mode before executing the rest of the function. This
allows these functions to be called from non­interworking
code.

-mcaller-super-interworking

Allow all calls via function pointers (including virtual
functions) to execute correctly regardless of whether the
target code has been compiled for interworking or not.
There is a small overhead in the cost of executing a
function pointer if this option is enabled.