Re: [PATCH] MicroBlaze support - 1 of 6 - documentation

[Michael Eager <eager at eagercon dot com>]

Joseph S. Myers wrote:
> On Thu, 4 Feb 2010, Michael Eager wrote:
>
> >   * doc/install.texi( microblaze-*-elf): Add.
>
> Swap "(" and " " here.
>
> >   * doc/invoke.texi (microblaze options): Add descriptions for
> >   MicroBlaze-specific options.
>
> The section appears to be called "MicroBlaze Options", so the log entry 
> should use that capitalization.
>
> > +@item -mmemcpy
> > +@opindex mmemcpy
> > +Don't optimize block moves, use memcpy.
>
> @code{memcpy}.
>
> > +@item -mno-clearbss
> > +@opindex mno-clearbss
> > +Clear the BSS to zero and place zero initialized in BSS.
>
> Why do you need a target-specific option?  I'd expect the 
> target-independent -fno-zero-initialized-in-bss to suffice.  If this 
> option means something different from what the target-independent option 
> controls, you need more documentation to explain the difference, with a 
> cross-reference in that documentation to the target-independent option.

This is needed for backward compatibility with existing usage.  I've
documented this option as deprecated with an xref to
-fno-zero-initialized-in-bss.  I also added a warning if it is used.

> > +@item -mxl-stack-check
> > +@opindex mxl-stack-check
> > +Check for stack overflow at runtime.
>
> Is there a reason you can't hook up whatever target-specific logic there 
> is to the target-independent -fstack-check option?  Again, more 
> documentation of the difference needed if so.

Similarly.
http://gcc.gnu.org/viewcvs?view=revision&revision=156791
or
svn diff svn://gcc.gnu.org/svn/gcc/branches/microblaze -r r156790:r156791

> > +Select application model @var{app-model}.  Valid models are 
> > +@table @samp
> > +@var{executable} -- normal executable (default), uses startup code crt0.o.
>
> I think you mean
>
>   @table @samp
>   @item executable
>   normal executable (default), uses startup code crt0.o.
>
> and similar for subsequent items.
>
> > +@var{xmdstub} -- for use with Xilinx Microprocessor Debugger (XMD) based 
> > +software intrusive debug agent called xmdstub. This uses startup file 
> > +crt1.o and sets the start address of the program to be 0x800.
>
> @file{crt1.o}.
>
> > +@var{bootstrap} -- for applications that are loaded using a bootloader.
> > +This model uses startup file crt2.o which does not contain a processor 
>
> @file{crt2.o}
>
> > +within a monitoring application. This model uses crt3.o as a startup file.
>
> @file{crt3.o}
>
> > +Option -xl-mode-@var{app-model} is a deprecated alias for 
> > +-mxl-mode-@var{app-model}.
>
> New ports shouldn't be adding deprecated options, but if it's really 
> necessary then use @option{-xl-mode-@var{app-model}}, 
> @option{-mxl-mode-@var{app-model}}.
>
> > +@item MicroBlaze ---@file{config/microblaze/constraints.md}
>
> Remove the space before "---".

Revised doc patch attached.

--
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077


diff -urNp --exclude '*.swp' --exclude DEV-PHASE --exclude '\.svn' --exclude CVS gcc-head/gcc/doc/contrib.texi mb-gcc/gcc/doc/contrib.texi
--- gcc-head/gcc/doc/contrib.texi	2010-01-05 13:46:04.000000000 -0800
+++ mb-gcc/gcc/doc/contrib.texi	2010-02-05 13:20:21.000000000 -0800
@@ -238,6 +238,9 @@ architecture, libio maintenance, and ear
 Zdenek Dvorak for a new loop unroller and various fixes.
 
 @item
+Michael Eager for his work on the Xilinx MicroBlaze port.
+
+@item
 Richard Earnshaw for his ongoing work with the ARM@.
 
 @item
diff -urNp --exclude '*.swp' --exclude DEV-PHASE --exclude '\.svn' --exclude CVS gcc-head/gcc/doc/extend.texi mb-gcc/gcc/doc/extend.texi
--- gcc-head/gcc/doc/extend.texi	2010-01-05 13:46:04.000000000 -0800
+++ mb-gcc/gcc/doc/extend.texi	2010-02-03 18:53:16.000000000 -0800
@@ -2507,8 +2507,8 @@ interrupt handler.  The compiler will ge
 sequences suitable for use in an interrupt handler when this attribute
 is present.
 
-Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, and
-SH processors can be specified via the @code{interrupt_handler} attribute.
+Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze,
+and SH processors can be specified via the @code{interrupt_handler} attribute.
 
 Note, on the AVR, interrupts will be enabled inside the function.
 
@@ -3028,6 +3028,14 @@ Use this attribute on the Blackfin, H8/3
 all registers except the stack pointer should be saved in the prologue
 regardless of whether they are used or not.
 
+@item save_volatiles
+@cindex save volatile registers on the MicroBlaze
+Use this attribute on the MicroBlaze to indicate that the function is
+an interrupt handler.  All volatile registers (in addition to non-volatile 
+registers) will be saved in the function prologue.  If the function is a leaf 
+function, only volatiles used by the function are saved.  A normal function 
+return is generated instead of a return from interrupt.  
+
 @item section ("@var{section-name}")
 @cindex @code{section} function attribute
 Normally, the compiler places the code it generates in the @code{text} section.
diff -urNp --exclude '*.swp' --exclude DEV-PHASE --exclude '\.svn' --exclude CVS gcc-head/gcc/doc/install.texi mb-gcc/gcc/doc/install.texi
--- gcc-head/gcc/doc/install.texi	2010-02-02 08:10:08.000000000 -0800
+++ mb-gcc/gcc/doc/install.texi	2010-02-03 18:53:16.000000000 -0800
@@ -2906,6 +2906,8 @@ information are.
 @item
 @uref{#mep-x-elf,,mep-*-elf}
 @item
+@uref{#microblaze-x-elf,,microblaze-*-elf}
+@item
 @uref{#mips-x-x,,mips-*-*}
 @item
 @uref{#mips-sgi-irix5,,mips-sgi-irix5}
@@ -3748,7 +3750,6 @@ both of which were ABI changes.  However
 original ABI by configuring for @samp{m68k-uclinuxoldabi} or
 @samp{m68k-@var{vendor}-uclinuxoldabi}.
 
-
 @html
 <hr />
 @end html
@@ -3759,6 +3760,13 @@ This configuration is intended for embed
 @html
 <hr />
 @end html
+@heading @anchor{microblaze-x-elf}microblaze-*-elf
+Xilinx MicroBlaze processor.
+This configuration is intended for embedded systems.
+
+@html
+<hr />
+@end html
 @heading @anchor{mips-x-x}mips-*-*
 If on a MIPS system you get an error message saying ``does not have gp
 sections for all it's [sic] sectons [sic]'', don't worry about it.  This
diff -urNp --exclude '*.swp' --exclude DEV-PHASE --exclude '\.svn' --exclude CVS gcc-head/gcc/doc/invoke.texi mb-gcc/gcc/doc/invoke.texi
--- gcc-head/gcc/doc/invoke.texi	2010-02-02 08:10:08.000000000 -0800
+++ mb-gcc/gcc/doc/invoke.texi	2010-02-05 14:30:33.000000000 -0800
@@ -680,6 +680,13 @@ Objective-C and Objective-C++ Dialects}.
 -mmult -mno-opts -mrepeat -ms -msatur -msdram -msim -msimnovec -mtf @gol
 -mtiny=@var{n}}
 
+@emph{MicroBlaze Options}
+@gccoptlist{-msoft-float -mhard-float -msmall-divides -mcpu=@var{cpu} @gol
+-mmemcpy -mxl-soft-mul -mxl-soft-div -mxl-barrel-shift @gol
+-mxl-pattern-compare -mxl-stack-check -mxl-gp-opt -mno-clearbss @gol
+-mxl-multiply-high -mxl-float-convert -mxl-float-sqrt @gol
+-mxl-mode-@var{app-model}}
+
 @emph{MIPS Options}
 @gccoptlist{-EL  -EB  -march=@var{arch}  -mtune=@var{arch} @gol
 -mips1  -mips2  -mips3  -mips4  -mips32  -mips32r2 @gol
@@ -9541,6 +9548,7 @@ platform.
 * M68hc1x Options::
 * MCore Options::
 * MeP Options::
+* MicroBlaze Options::
 * MIPS Options::
 * MMIX Options::
 * MN10300 Options::
@@ -13446,6 +13454,103 @@ register.  The default for this option i
 
 @end table
 
+@node MicroBlaze Options
+@subsection MicroBlaze Options
+@cindex MicroBlaze Options
+
+@table @gcctabopt
+
+@item -msoft-float
+@opindex msoft-float
+Use software emulation for floating point (default).
+
+@item -mhard-float
+@opindex mhard-float
+Use hardware floating point instructions.
+
+@item -mmemcpy
+@opindex mmemcpy
+Don't optimize block moves, use @code{memcpy}.
+
+@item -mno-clearbss
+@opindex mno-clearbss
+This option is deprecated.  Use -fno-zero-initialized-in-bss instead.
+
+@item -mcpu=@var{cpu-type}
+@opindex mcpu=
+Use features of and schedule code for given CPU.
+Supported values are in the format vX.YY.Z, where X is a major version, YY 
+is the minor version, and Z is compatiblity code.  Example values are 
+@samp{v3.00.a}, @samp{v4.00.b}, @samp{v5.00.a}, @samp{v5.00.b}, 
+@samp{v5.00.b}, @samp{v6.00.a}. 
+@item -mxl-soft-mul
+@opindex mxl-soft-mul
+Use software multiply emulation (default).
+
+@item -mxl-soft-div
+@opindex mxl-soft-div
+Use software emulation for divides (default).
+
+@item -mxl-barrel-shift
+@opindex mxl-barrel-shift
+Use the hardware barrel shifter.
+
+@item -mxl-pattern-compare
+@opindex mxl-pattern-compare
+Use pattern compare instructions.
+
+@item -msmall-divides
+@opindex msmall-divides
+Use table lookup optimization for small signed integer divisions.
+
+@item -mxl-stack-check
+@opindex mxl-stack-check
+This option is deprecated.  Use -fstack-check instead.
+
+@item -mxl-gp-opt
+@opindex mxl-gp-opt
+Use GP relative sdata/sbss sections.
+
+@item -mxl-multiply-high
+@opindex mxl-multiply-high
+Use multiply high instructions for high part of 32x32 multiply.
+
+@item -mxl-float-convert
+@opindex mxl-float-convert
+Use hardware floating point converstion instructions.
+
+@item -mxl-float-sqrt
+@opindex mxl-float-sqrt
+Use hardware floating point square root instruction.
+
+@item -mxl-mode-@var{app-model}
+Select application model @var{app-model}.  Valid models are 
+@table @samp
+@item executable
+normal executable (default), uses startup code @file{crt0.o}.
+
+@item xmdstub
+for use with Xilinx Microprocessor Debugger (XMD) based 
+software intrusive debug agent called xmdstub. This uses startup file 
+@file{crt1.o} and sets the start address of the program to be 0x800.
+
+@item bootstrap
+for applications that are loaded using a bootloader.
+This model uses startup file @file{crt2.o} which does not contain a processor 
+reset vector handler. This is suitable for transferring control on a 
+processor reset to the bootloader rather than the application.
+
+@item novectors
+for applications that do not require any of the 
+MicroBlaze vectors. This option may be useful for applications running
+within a monitoring application. This model uses @file{crt3.o} as a startup file.
+@end table
+
+Option @option{-xl-mode-@var{app-model}} is a deprecated alias for 
+@option{-mxl-mode-@var{app-model}}.
+
+@end table
+
 @node MIPS Options
 @subsection MIPS Options
 @cindex MIPS options
diff -urNp --exclude '*.swp' --exclude DEV-PHASE --exclude '\.svn' --exclude CVS gcc-head/gcc/doc/md.texi mb-gcc/gcc/doc/md.texi
--- gcc-head/gcc/doc/md.texi	2010-01-05 13:46:04.000000000 -0800
+++ mb-gcc/gcc/doc/md.texi	2010-02-05 08:34:44.000000000 -0800
@@ -2661,7 +2661,15 @@ A register indirect address without offs
 @item Z
 Symbolic references to the control bus.
 
+@end table
 
+@item MicroBlaze---@file{config/microblaze/constraints.md}
+@table @code
+@item d
+A general register (@code{r0} to @code{r31}).
+
+@item z
+A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}).
 
 @end table