[SH] Document function attributes

[Oleg Endo <oleg dot endo at t-online dot de>]

Hello,

The attached patch adds documentation for SH specific function
attributes which haven't been documented yet.
Tested with 'make info dvi pdf'.
OK?

Cheers,
Oleg

gcc/ChangeLog:

	* config/sh/sh.c: Update function attribute comments.
	* doc/extend.texi (function_vector): Rephrase SH2A specific 
	part.
	(nosave_low_regs, renesas, trapa_handler): Document SH specific 
	attributes.
	(sp_switch, trap_exit): Add to index.

Index: gcc/config/sh/sh.c
===================================================================
--- gcc/config/sh/sh.c	(revision 192417)
+++ gcc/config/sh/sh.c	(working copy)
@@ -9451,30 +9451,42 @@
   return;
 }
 
-/* Supported attributes:
+/*------------------------------------------------------------------------------
+/* Target specific attributes
+  Supported attributes are:
 
-   interrupt_handler -- specifies this function is an interrupt handler.
+   * interrupt_handler
+	Specifies this function is an interrupt handler.
 
-   trapa_handler - like above, but don't save all registers.
+   * trapa_handler
+	Like interrupt_handler, but don't save all registers.
 
-   sp_switch -- specifies an alternate stack for an interrupt handler
-   to run on.
+   * sp_switch
+	Specifies an alternate stack for an interrupt handler to run on.
 
-   trap_exit -- use a trapa to exit an interrupt function instead of
-   an rte instruction.
+   * trap_exit
+	Use a trapa to exit an interrupt function instead of rte.
 
-   nosave_low_regs - don't save r0..r7 in an interrupt handler.
-     This is useful on the SH3 and upwards,
-     which has a separate set of low regs for User and Supervisor modes.
-     This should only be used for the lowest level of interrupts.  Higher levels
-     of interrupts must save the registers in case they themselves are
-     interrupted.
+   * nosave_low_regs
+	Don't save r0..r7 in an interrupt handler function.
+	This is useful on SH3* and SH4*, which have a separate set of low
+	regs for user and privileged modes.
+	This is mainly to be used for non-reentrant interrupt handlers (i.e.
+	those that run with interrupts disabled and thus can't be
+	interrupted thenselves).
 
-   renesas -- use Renesas calling/layout conventions (functions and
-   structures).
+   * renesas
+	Use Renesas calling/layout conventions (functions and structures).
 
-   resbank -- In case of an ISR, use a register bank to save registers
-   R0-R14, MACH, MACL, GBR and PR.  This is useful only on SH2A targets.
+   * resbank
+	In case of an interrupt handler function, use a register bank to
+	save registers R0-R14, MACH, MACL, GBR and PR.
+	This is available only on SH2A targets.
+
+   * function_vector
+	Declares a function to be called using the TBR relative addressing
+	mode.  Takes an argument that specifies the slot number in the table
+	where this function can be looked up by the JSR/N @@(disp8,TBR) insn.
 */
 
 /* Handle a 'resbank' attribute.  */
Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi	(revision 192417)
+++ gcc/doc/extend.texi	(working copy)
@@ -2682,17 +2682,16 @@
 the function vector has a limited size (maximum 128 entries on the H8/300
 and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector.
 
-In SH2A target, this attribute declares a function to be called using the
+On SH2A targets, this attribute declares a function to be called using the
 TBR relative addressing mode.  The argument to this attribute is the entry
 number of the same function in a vector table containing all the TBR
-relative addressable functions.  For the successful jump, register TBR
-should contain the start address of this TBR relative vector table.
-In the startup routine of the user application, user needs to care of this
-TBR register initialization.  The TBR relative vector table can have at
-max 256 function entries.  The jumps to these functions will be generated
-using a SH2A specific, non delayed branch instruction JSR/N @@(disp8,TBR).
-You must use GAS and GLD from GNU binutils version 2.7 or later for
-this attribute to work correctly.
+relative addressable functions.  For correct operation the TBR must be setup
+accordingly to point to the start of the vector table before any functions with
+this attribute are invoked.  Usually a good place to do the initialization is
+the startup routine.  The TBR relative vector table can have at max 256 function
+entries.  The jumps to these functions will be generated using a SH2A specific,
+non delayed branch instruction JSR/N @@(disp8,TBR).  You must use GAS and GLD
+from GNU binutils version 2.7 or later for this attribute to work correctly.
 
 Please refer the example of M16C target, to see the use of this
 attribute while declaring a function,
@@ -3251,6 +3250,13 @@
 take function pointer arguments.  The @code{nothrow} attribute is not
 implemented in GCC versions earlier than 3.3.
 
+@item nosave_low_regs
+@cindex @code{nosave_low_regs} attribute
+Use this attribute on SH targets to indicate that an @code{interrupt_handler}
+function should not save and restore registers R0..R7.  This can be used on SH3*
+and SH4* targets which have a second R0..R7 register bank for non-reentrant
+interrupt handlers.
+
 @item optimize
 @cindex @code{optimize} function attribute
 The @code{optimize} attribute is used to specify that a function is to
@@ -3428,6 +3434,11 @@
 This supports mixing legacy codes that run with a 4-byte aligned stack
 with modern codes that keep a 16-byte stack for SSE compatibility.
 
+@item renesas
+@cindex @code{renesas} attribute
+On SH targets this attribute specifies that the function or struct follows the
+Renesas ABI.
+
 @item resbank
 @cindex @code{resbank} attribute
 On the SH2A target, this attribute enables the high-speed register
@@ -3538,6 +3549,7 @@
 function, @code{signal} will be silently ignored.
 
 @item sp_switch
+@cindex @code{sp_switch} attribute
 Use this attribute on the SH to indicate an @code{interrupt_handler}
 function should switch to an alternate stack.  It expects a string
 argument that names a global variable holding the address of the
@@ -3929,10 +3941,16 @@
 slightly under 32kbytes of data.
 
 @item trap_exit
+@cindex @code{trap_exit} attribute
 Use this attribute on the SH for an @code{interrupt_handler} to return using
 @code{trapa} instead of @code{rte}.  This attribute expects an integer
 argument specifying the trap number to be used.
 
+@item trapa_handler
+@cindex @code{trapa_handler} attribute
+On SH targets this function attribute is similar to @code{interrupt_handler}
+but it does not save and restore all registers.
+
 @item unused
 @cindex @code{unused} attribute.
 This attribute, attached to a function, means that the function is meant