[Bug-gnupress] Modifications to gcc.008.txt (#1)

[Paul A. Crable]

These are the modification I propose to gcc.008.txt, commencing at
the top of the file.  They are options that complete section 3.7.17

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

Replace

"-mtrap-precision=trap-precision
"In the Alpha architecture, oating point traps are imprecise. This
means without software assistance it is impossible to recover from a
floating trap and program execution normally needs to be terminated.
GCC can generate code that can assist operating system trap handlers
in determining the exact location that caused a floating point trap.
Depending on the requirements of an application, different levels of
precisions can be selected:

"`p' Program precision. This option is the default and means
a trap handler can only identify which program caused
a oating point exception.

"`f' Function precision. The trap handler can determine the
function that caused a oating point exception.

"`i' Instruction precision. The trap handler can determine
the exact instruction that caused a oating point excep­
tion.

"Other Alpha compilers provide the equivalent options called
`-scope_safe' and `-resumption_safe'."

with

"-mtrap-precision=trap-precision
    "Generate code that assists operating system
    trap handlers in determining the location at
    which a floating point trap occured.  In the
    Alpha architecture, floating point traps are
    imprecise.  Without software assistance the
    result of a floating point trap is
    unpredictable and program execution should be
    terminated.  trap-precision specifies the
    level of precision at which the location of
    the offending instruction may be located:

        "`p' Program precision.  Allow a trap handler
        to identify the program causing a floating
        point exception.  If -mtrap-precision is not
        specified, GCC assumes trap-precision to be
        this value.

        "`f' Function precision.  Allow a trap trap
        handler to determine the function that caused
        a floating point exception.

        "`i' Instruction precision.  Allow the trap
        handler to determine the exact instruction
        that caused a floating point exception.

    "Other Alpha compilers provide the equivalent
    options called `-scope_safe' and `-
    resumption_safe'.

Replace

"-mieee-conformant
"This option marks the generated code as IEEE conformant. You must
not use this option unless you also specify `-mtrap-precision=i' and
either `-mfp-trap-mode=su' or `-mfp-trap-mode=sui'. Its only effect
is to emit the line `.eflag 48' in the function prologue of the
generated as­ sembly le. UnderDEC Unix, this has the effect that
IEEE­conformant math library routines will be linked in."

with

"-mieee-conformant
    "Mark the code as conforming to IEEE
    ??????????????????.  You must also specify `-
    mtrap-precision=i', and either `-mfp-trap-
    mode=su' or `-mfp-trap-mode=sui'.  This option
    causes the line `.eflag 48' to be placed in
    the function prologue of the generated
    assembler code.  Under DEC Unix, this also
    causes IEEE­conformant math routines to be
    linked in."

Replace

"-mbuild-constants
"Normally GCC examines a 32­ or 64­bit integer constant to see if it
can construct it from smaller constants in two or three instructions.
If it cannot, it will output the constant as a literal and generate
code to load it from the data segment at runtime.

"Use this option to require GCC to construct all integer constants
using code, even if it takes more instructions (the maximum is six).
You would typically use this option to build a shared library dynamic
loader. Itself a shared library, it must relocate itself in memory
before it can find the variables and constants in its own data
segment."

with

"-mbuild-constants
    "Construct all integer constants using code.
    Normally GCC examines a 32­ or 64­bit integer
    constant to determine whether the constant can
    be constructed from smaller constants using
    two or three instructions.  If it cannot, GCC
    will output the constant as a literal and
    generate code that loads it from the data
    segment at run time.  This option forces GCC
    to construct all integer constants using code
    even if doing so generates more instructions.
    You typically would use this option when
    building a shared library dynamic loader."

Replace

"-mbwx
"-mno-bwx
"-mcix
"-mno-cix
"-mfix
"-mno-fix
"-mmax
"-mno-max
"Indicate whether GCC should generate code to use the optional BWX,
CIX, FIX and MAX instruction sets. The default is to use the instruc­
tion sets supported by the CPU type specied via `-mcpu=' option or
that of the CPU on which GCC was built if none was specied.

with

"-mbwx
"-mno-bwx
"-mcix
"-mno-cix
"-mfix
"-mno-fix
"-mmax
"-mno-max
    "Generate code using the optional BWX (-mbwx),
    CIX (-mcixv), FIX (-mfix), and MAX (-mmax)
    instructions; or force GCC to not use the
    instructions (-mno-bwx, -mno-cix, -mno-fix, or
    -mno-max, respectively).  If this option is
    not specified, GCC will generate output using
    the instruction sets supported by the CPU type
    specified via the `-mcpu=' option, or, if that
    option is not specified, that of the CPU for
    which GCC was configured."

Replace

"-mfloat-vax
"-mfloat-ieee
"Generate code that uses (does not use) VAX F and G oating point
arithmetic instead of IEEE single and double precision."

with

"-mfloat-vax
"-mfloat-ieee
    "Generate code that uses VAX F and G floating
    point arithmetic (-mfloat-vax) or of IEEE
    single and double precision arithmetic (-
    mfloat-ieee).  If neither is specified, then
    ???????????????????????"

Replace

"-mexplicit-relocs
"-mno-explicit-relocs
"Older Alpha assemblers provided no way to generate symbol relo­
cations except via assembler macros. Use of these macros does not
allow optimal instruction scheduling. GNU binutils as of version 2.12
supports a new syntax that allows the compiler to explicitly mark
which relocations should apply to which instructions. This option is
mostly useful for debugging, as GCC detects the capabilities of the
assembler when it is built and sets the default accordingly."

with

"-mexplicit-relocs
"-mno-explicit-relocs
    "Generate code that explicitly marks which
    relocations should apply to which instructions
    (-mexplicit-relocs).  If -mno-explicit-relocs
    is specified, do not generate such code.
    Older Alpha assemblers could only generate
    symbol relocations using macros.  Use of these
    macros, however, did not allow optimal
    instruction scheduling.  GNU binutils version
    2.12 and later supports a new syntax that
    allows the compiler to explicitly match
    relocations with instructions.  This option is
    most useful for debugging.  GCC detects the
    capabilities of the assembler when it is built
    and sets the default accordingly."

Replace

"-msmall-data
"-mlarge-data
"When `-mexplicit-relocs' is in effect, static data is accessed via
gp­ relative relocations. When `-msmall-data' is used, objects 8
bytes long or smaller are placed in a small data area(the .sdata and
sbss sections) and are accessed via 16­bit relocations off of the
$gpregister. This limits the size of the small data area to 64KB, but
allows the variables to be directly accessed via a single
instruction.

"The default is `-mlarge-data'. With this option the data area is
limited to just below 2GB. Programs that require more than 2GB of
data must use malloc or mmap to allocate the data in the heap instead
of in the program's data segment.

"When generating code for shared libraries, `-fpic' implies
`-msmall-data' and `-fPIC' implies `-mlarge-data'.

with

"-msmall-data
"-mlarge-data
    "Place objects eight bytes long or smaller in
    a small data area, the .sdata and .sbss
    sections, and access them via 16­bit
    relocations off of the $gpregister (-msmall-
    data).  If -mlarge-data is specified, do not
    place the data in the small data area.

    "When `-mexplicit-relocs' is specified, static
    data are accessed via gp­relative relocations.
    When `-msmall-data' is used, the size of the
    data area is limited to 64 kb but allows the
    variables can be accessed with a single
    instruction.  If neither is specified, `-
    mlarge-data' is assumed.  This option expands
    the data area to just under two GB.  Note that
    programs that require more than 2 GB of data
    must use malloc or mmap to allocate the data
    in the heap instead of in the program's data
    segment.

    "When generating code for shared libraries, `-
    fpic' assumes `-msmall-data' is set, while `-
    fPIC' assumes -mlarge-data."

Replace the current definition of the option -mcpu=cpu_type with

"-mcpu=cpu_type
    "Set the instruction set and instruction
    scheduling parameters for machine type
    cpu_type.  You may specify either the `EV'
    style name or the chip number. GCC supports
    scheduling parameters for the EV4, EV5 and EV6
    families of processors and will choose the
    default values for the instruction set from
    the processor specified. If you do not specify
    a processor type, GCC will default to the
    processor for which the compiler was built.
    "Supported values for cpu type are:

        `ev4'

        `ev45'

        `21064' Schedules as an EV4 and has no
        instruction set extensions.

        `ev5'

        `21164' Schedules as an EV5 and has no
        instruction set extensions.

        `ev56'

        `21164a' Schedules as an EV5 and supports the
        BWX extension.

        `pca56'

        `21164pc'

        `21164PC' Schedules as an EV5 and supports the
        BWX and MAX extensions.

        `ev6'

        `21264' Schedules as an EV6 and supports the
        BWX, FIX, and MAX extensions.

        `ev67'

        `21264a' Schedules as an EV6 and supports the
        BWX, CIX, FIX, and MAX extensions."

Replace

"-mmemory-latency=time
"Sets the latency the scheduler should assume for typical memory ref­
erences as seen by the application. This number is highly dependent
on the memory access patterns used by the application and the size of
the external cache on the machine. Valid options for timeare
`number' A decimal number representing clock cycles.
`L1'
`L2'
`L3'
`main' The compiler contains estimates of the number of clock cycles
for ìtypicalî EV4 & EV5 hardware for the Level 1, 2 & 3 caches (also
called Dcache, Scache, and Bcache), as well as to main memory. Note
that L3 is only valid for
EV5."

with

"-mmemory-latency=latency_time
    "Set to latency_time the latency that the
    scheduler should assume for typical memory
    references seen by the application.  Valid
    options for time are:

        `number' A decimal number representing clock
        cycles.  number may range between ?????????
        and ????????????

        `L1'

        `L2'

        `L3'

        `main' The compiler contains estimates of the
        number of clock cycles for typical EV4 & EV5
        hardware for the Level 1, 2 & 3 caches (also
        called Dcache, Scache, and Bcache), as well as
        to main memory.  Note that L3 is only valid
        for EV5.

    This number is highly dependent on the memory
    access patterns used by the application and
    the size of the external cache on the machine.
    If -mmemory-latency is not specified, then
    latency_time is assumed to be ???????????"

Paul A. Crable.  Portland, Oregon, USA