[Bug-gnupress] Proposed changes to gcc006.txt (#1)

[Paul A. Crable]

Is there a way I can get my section of the document (gcc006.txt) as
ASCII text or as an .RTF file?

Is it possible to present data in the form of a table?

Might we not use a word processor, such as Open Office or ABI, to
submit changes?  This would allow us to mark up the document so
others could view the existing text and the proposed changes
together.  The 'Replace "Mumble" with "More mumble"' paradigm is
difficult to comprehend. Both Open Office and ABI are free.

I find that I am making changes to virtually every paragraph, so I
intend to forward completely rewritten sections for your
consideration, rather than first quoting the old text and then the
replacement.

In any case, this is the first set of modifications to gcc006.txt:

1.  The section headings seem a little confusing to me.

    They are:

        3.17.1 M680x0 Options
        3.17.2 M68hc1x Options
        3.17.3 VAX Options
        3.17.4 SPARC Options
        3.17.5 ARM Options
        3.17.6 MN10200 Options
        3.17.7 MN10300 Options
        3.17.8 M32R/D Options
        3.17.9 M88K Options
        3.17.10 IBM RS/6000 and PowerPC Options

    I suggest repartitioning the set of options as follows:

        3.17.1 Motorola Options
                (to contain these existing sections merged as one:
                        3.17.1 M680x0 Options
                        3.17.2 M68hc1x Options
                        3.17.8 M32R/D Options
                        3.17.9 M88K Options)
        3.17.2 VAX Options
        3.17.3 SPARC Options
        3.17.4 ARM Options
        3.17.5 Mitsubishi Options
                (to contain existing sections:
                        3.17.6 MN10200 Options
                        3.17.7 MN10300 Options)
        3.17.6 IBM RS/6000 and PowerPC Options

2.  Throughout this section many option definitions begin with
"Generate output for a Mumble microprocessor...".  I propose making a
global substition, changing every instance to "Generate code for a
Mumble microprocessor...".  "Output" is too vague; the principal
output is object code so let's just say so.

3.  This is the rewrite of existing section 3.17.1, M680x0 Options:

    3.17.1 M680x0 Options

    These are the `-m' options applicable to the Motorola 68xxx
series microcontroller.

    -m68000
    -mc68000
        Either argument may be used.  Generate code for a 68000. If the
compiler has been configured for 68000­based microcontrollers, this
option is set by default and may be omitted.  If the compiler has
been configured for other systems, then this option will force GCC to
generate code for the 68000.  Use this option for microcontrollers
with a 68000 or EC000 core, including the 68008, 68302, 68306, 68307,
68322, 68328 and 68356.

    -m68020
    -mc68020
        Either argument may be used.  Generate code for a 68020. If the
compiler has been configured for 68020­based microcontrollers, this
option is set by default and may be omitted.  If the compiler has
been configured for other systems, then this option will force GCC to
generate code for the 68020.

    -m68881
        Generate code for a ?????. The code will invoke 68881
instruction for floating point processing.  Unless the '--nfp' option
was specified when the compiler was configured, this option is on by
default and may be omitted.

[ed note:  The preceeding two sentences don't make sense to me]

    -m68030
        Generate code for a 68030. If the compiler has been configured
for 68030­based microcontrollers, this option is set by default and
may be omitted.  If the compiler has been configured for other
systems, then this option will force GCC to generate code for the
68030.

    -m68040
        Generate code for a 68040. If the compiler has been configured
for 68040­based microcontrollers, this option is set by default and
may be omitted.  If the compiler has been configured for other
systems, then this option will force GCC to generate code for the
68040.

    [ed. note:  I don't understand the next two sentences]

This option inhibits the production of 68881/68882 instructions that
have to be emulated by software on the 68040. Use this option if your
68040 does not have code to emulate those instructions.

    -m68060
        Generate code for a 68060. If the compiler has been configured
for 68060­based microcontrollers, this option is set by default and
may be omitted.  If the compiler has been configured for other
systems, then this option will force GCC to generate code for the
68060.

    [ed. note:  Likewise with these two sentences]

This option inhibits the use of 68020 and 68881/68882 instructions
that have to be emulated by software on the 68060. Use this option if
your 68060 does not have code to emulate those instructions.

    -mcpu32
        Generate code for a CPU32. If the compiler has been configured
for CPU32­based microcontrollers, this option is set by default and
may be omitted.  If the compiler has been configured for other
systems, then this option will force GCC to generate code for the
CPU32.  Use this option for microcontrollers with a CPU32 or CPU32+
core, including the 68330, 68331, 68332, 68333, 68334, 68336, 68340,
68341, 68349, and 68360.

    -m5200
        Generate code for a 520X 'coldfire'-family cpu. If the compiler
has been configured for 520X­based systems, this option is set by
default and may be omitted.  If the compiler has been configured for
other systems, then this option will force GCC to generate code for a
a 520X 'coldfire'-family cpu.  Use this option for microcontroller
with a 5200 core, including the MCF5202, MCF5203, MCF5204, and
MCF5202.

    -m68020-40
        Generate code for a 68040 but do not use the new instructions.
The resulting code will run well on either a 68020/68881, a 68030, or
a 68040. The code uses the 68881 instructions that are emulated on
the 68040.

    [ed note:  What are the "new instructions"; can't we be more
specific?]

    -m68020-60
        Generate output for a 68060 but do not use the new instructions.
The resulting code will run well on 68020/68881, a 68030, or a 68040.
The code uses the 68881 instructions that are emulated on the 68060.

    -mfpa
        Generate code containing Sun FPA instructions for floating point
processing.

    -msoft-float
        Generate code containing calls to software for floating point
processing.  Be advised that supporting libraries are not available
for all m68k targets.

    [ed note:  I don't understand what the next three sentences are
saying]

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. The embedded targets `m68k-*-aout' and
`m68k-*-coff' do provide software floating point support.

    -mshort
        Force variables of type int to be 16 bits in width.

    -mbitfield
    -mnobitfield
        Do (-mbitfield) or do not (-mnobitfield) use the bit­feld
instructions.  If the `-m68000', `-mcpu32' or `-m5200' option is set,
then `-mnobitfield' is the default value.  If the `-m68020' option is
set, then `-mbitfield' is the default value. For other processor
options, the default value is ?????.

    -mrtd
        Use a non-standard calling convention, in which functions that
take a fixed number of arguments return with the RTD instruction. RTD
pops the arguments from the stack while returning, saving one
instruction cycle.  This convention is incompatible with that used on
Unix systems, so do not attempt to link to call libraries compiled
with the Unix compiler.  The RTD instruction is supported on the
68010, 68020, 68030, 68040, 68060 and CPU32 processors, but not on
the 68000 or 5200.

        If you set this option, you must provide prototypes for all
functions that take a variable number of arguments (such as printf);
otherwise the code will be unusable.  Likewise, calling a function
with too many arguments will result in unusable code.  Calling
functions with extra arguments, however, is harmless; the extra
arguments are ignored.

    -malign-int
    -mno-align-int
        Align int, long, long long, float, double, and long double
variables on a 32­bit boundary (`-malign-int') or a 16­bit boundary
(`-mno-align-int').  Aligning variables on 32­bit boundaries produces
code that runs somewhat faster on processors with 32­bit busses, but
wastes some memory.  Be advise that the `-malign-int' switch will
align structures containing these types in a manner that differs from
most published application binary interface specifications for the
m68000.

    -mpcrel
        Use the pc­relative addressing mode of the 68000 directly,
instead of using a global offset table. If -mpcrel is set, then -fpic
is set by default, allowing at most a 16­bit offset for pc­relative
addressing.

    [ed note:  The following sentence seems to contradict the
preceeding two]

    `-fPIC' is not presently supported with `-mpcrel', though this
could be supported for 68020 and higher processors.

    -mno-strict-align
    -mstrict-align
        Assume (?????) or do not assume (?????) that unaligned memory
references will be handled by the system.

    [ed note:  The document is not clear which argument goes with
which choice]