doc for x86 features

[Dave Love <d dot love at dl dot ac dot uk>]

There's currently no description I can see of the much-requested
post-2.7 [56]86 features.  I'd like to incite someone who knows what
they're about to fix the attempt below, derived by trying to decipher
i386.[ch].

[Why is the x86 different from other targets with -mcpu=, -march=
rather than -mcpu=,-mtune=?  I don't remember the discussion of this
and the result seems confusing.]

BTW, is there a good reason why the compiler options don't have index
entries?  I've felt the need for them at times.

--- NEWS	1997/11/17 18:08:41	1.1
+++ NEWS	1997/11/17 18:10:51
@@ -15,6 +15,12 @@
     Linux running on PowerPC's.
     Embedded target m32r-elf.
 
+New features for the x86.
+
+    -mcpu=xxx
+    -march=xxx
+    -mpentium, -mpentiumpro
+
 New features for the Hitachi H8/300(H).
 
     -malign-300
--- invoke.texi	1997/11/17 17:32:34	1.1
+++ invoke.texi	1997/11/17 18:52:36
@@ -304,12 +304,13 @@
 -mstats  -EL  -EB  -G @var{num}  -nocpp
 
 @emph{i386 Options}
--m486  -m386  -mieee-fp  -mno-fancy-math-387
+-m486  -m386  -mpentium  -mpentiumpro  -mieee-fp  -mno-fancy-math-387
 -mno-fp-ret-in-387  -msoft-float  -msvr3-shlib
 -mno-wide-multiply  -mrtd  -malign-double
 -mreg-alloc=@var{list}  -mregparm=@var{num}
 -malign-jumps=@var{num}  -malign-loops=@var{num}
 -malign-functions=@var{num}
+-mcpu=@var{cpu type} -march=@var{cpu type}
 
 @emph{HPPA Options}
 -mbig-switch  -mdisable-fpregs  -mdisable-indexing  -mfast-indirect-calls
@@ -4453,14 +4454,55 @@
 @subsection Intel 386 Options
 @cindex i386 Options
 @cindex Intel 386 Options
+@cindex x86 Options
 
-These @samp{-m} options are defined for the i386 family of computers:
+These @samp{-m} options are defined for the i386 family of computers.
+The default is determined by the target for which the compiler was
+configured.
 
 @table @code
 @item -m486
 @itemx -m386
+@itemx -mno-386
+@itemx -mno-486
 Control whether or not code is optimized for a 486 instead of an
 386.  Code generated for an 486 will run on a 386 and vice versa.
+
+@samp{-m386} is equivalent to @samp{-mcpu=i386 -march=i386} and
+@samp{-m486} is equivalent to @samp{-mcpu=i486 -march=i486}.
+@samp{-mno-386} is equivalent to @samp{-m486} and @samp{-mno-486} is
+equivalent to @samp{-m386}.
+
+@item -mpentium
+@itemx -mpentiumpro
+@itemx -mno-pentium
+@itemx -mno-pentiumpro
+@cindex Pentium
+@cindex Pentium Pro
+Control whether or not code is generated for a Pentium or Pentium Pro.
+Code generated for these targets may not run on a 386 or 486.
+
+@samp{-mpentium} is equivalent to @samp{-mcpu=pentium} and
+@samp{-mpentiumpro} is equivalent to @samp{-mcpu=pentiumpro}.
+@samp{-mno-pentium} is equivalent to @samp{-mpentiumpro} and
+@samp{-mno-pentiumpro} is equivalent to @samp{-mpentium}.
+
+@item -mcpu=@var{cpu type}
+@itemx -march=@var{cpu type}
+@cindex i386
+@cindex i486
+@cindex i586
+@cindex i686
+where @var{cpu type} is @samp{i386}, @samp{i486}, @samp{pentium} or
+@samp{pentiumpro} and @samp{i586}, @samp{i686} are aliases for
+@samp{pentium} and @samp{pentiumpro} respectively.
+
+@samp{-mcpu=@var{cpu type}} sets the architecture type (instruction
+set), register usage and scheduling parameters for the given @var{cpu
+type}.  @samp{-march=@var{cpu type}} can be used to set the architecture
+separately from the scheduling parameters.  Thus @samp{-mcpu=i686
+-march=i486} specifies generation of code that will run on a 386 or 486
+but is scheduled for best results on a Pentium Pro.
 
 @item -mieee-fp
 @itemx -mno-ieee-fp