re PR target/51345 ([avr] Devices with 8-bit SP need their own multilib(s))

	PR target/51345
	* config/avr/avr.opt (-msp8): Document it.
	* doc/invoke.texi (AVR Options): Ditto.  And document related
	built-in macros.

From-SVN: r188070

gcc/ChangeLog

+2012-05-31  Georg-Johann Lay  <avr@gjlay.de>
+
+	PR target/51345
+	* config/avr/avr.opt (-msp8): Document it.
+	* doc/invoke.texi (AVR Options): Ditto.  And document related
+	built-in macros.
+
 2012-05-31   Diego Novillo  <dnovillo@google.com>
 
        * configure.ac (CXX_FOR_BUILD): Define and substitute.

gcc/config/avr/avr.opt

@@ -76,4 +76,5 @@ When accessing RAM, use X as imposed by the hardware, i.e. just use pre-decremen
 
 ;; For rationale behind -msp8 see explanation in avr.h.
 msp8
-Target Report RejectNegative Undocumented Var(avr_sp8) Init(0)
+Target Report RejectNegative Var(avr_sp8) Init(0)
+The device has no SPH special function register. This option will be overridden by the compiler driver with the correct setting if presence/absence of SPH can be deduced from -mmcu=MCU.

gcc/doc/invoke.texi

@@ -11094,6 +11094,9 @@ known before code is located. Therefore, the assembler code generated by the
 compiler is the same, but the instructions in the executable may
 differ from instructions in the assembler code.
 
+Relaxing must be turned on if linker stubs are needed, see the
+section on @code{EIND} and linker stubs below.
+
 @item -mshort-calls
 @opindex mshort-calls
 Use @code{RCALL}/@code{RJMP} instructions even on devices with
@@ -11101,6 +11104,21 @@ Use @code{RCALL}/@code{RJMP} instructions even on devices with
 have the @code{CALL} and @code{JMP} instructions.
 See also the @code{-mrelax} command line option.
 
+@item -msp8
+@opindex msp8
+Treat the stack pointer register as an 8-bit register,
+i.e.@: assume the high byte of the stack pointer is zero.
+In general, you don't need to set this option by hand.
+
+This option is used internally by the compiler to select and
+build multilibs for architectures @code{avr2} and @code{avr25}.
+These architectures mix devices with and without @code{SPH}.
+For any setting other than @code{-mmcu=avr2} or @code{-mmcu=avr25}
+the compiler driver will add or remove this option from the compiler
+proper's command line, because the compiler then knows if the device
+or architecture has an 8-bit stack pointer and thus no @code{SPH}
+register or not.
+
 @item -mstrict-X
 @opindex mstrict-X
 Use address register @code{X} in a way proposed by the hardware.  This means
@@ -11163,6 +11181,13 @@ generates @emph{stubs}. Stubs are jump pads sometimes also called
 The stub contains a direct jump to the desired address.
 
 @item
+Linker relaxation must be turned on so that the linker will generate
+the stubs correctly an all situaltion. See the compiler option
+@code{-mrelax} and the linler option @code{--relax}.
+There are corner cases where the linker is supposed to generate stubs
+but aborts without relaxation and without a helpful error message.
+
+@item
 The default linker script is arranged for code with @code{EIND = 0}.
 If code is supposed to work for a setup with @code{EIND != 0}, a custom
 linker script has to be used in order to place the sections whose
@@ -11189,8 +11214,8 @@ static void
 __attribute__((section(".init3"),naked,used,no_instrument_function))
 init3_set_eind (void)
 @{
-    __asm volatile ("ldi r24,pm_hh8(__trampolines_start)\n\t"
-                    "out %i0,r24" :: "n" (&EIND) : "r24","memory");
+  __asm volatile ("ldi r24,pm_hh8(__trampolines_start)\n\t"
+                  "out %i0,r24" :: "n" (&EIND) : "r24","memory");
 @}
 @end example
 
@@ -11332,8 +11357,8 @@ The device has the @code{MOVW} instruction to perform 16-bit
 register-register moves.
 
 @item __AVR_HAVE_LPMX__
-The device has the @code{LPM R@var{n},Z} and @code{LPM
-R@var{n},Z+} instructions.
+The device has the @code{LPM R@var{n},Z} and
+@code{LPM R@var{n},Z+} instructions.
 
 @item __AVR_HAVE_MUL__
 The device has a hardware multiplier. 
@@ -11356,9 +11381,18 @@ with up to 128@tie{}KiB of program memory.
 
 @item __AVR_HAVE_8BIT_SP__
 @item __AVR_HAVE_16BIT_SP__
-The stack pointer (SP) is respectively 8 or 16 bits wide.
+The stack pointer (SP) register is treated as 8-bit respectively
+16-bit register by the compiler.
 The definition of these macros is affected by @code{-mtiny-stack}.
 
+@item __AVR_HAVE_SPH__
+@item __AVR_SP8__
+The device has the SPH (high part of stack pointer) special function
+register or has an 8-bit stack pointer, respectively.
+The definition of these macros is affected by @code{-mmcu=} and
+in the cases of @code{-mmcu=avr2} and @code{-mmcu=avr25} also
+by @code{-msp8}.
+
 @item __AVR_HAVE_RAMPD__
 @item __AVR_HAVE_RAMPX__
 @item __AVR_HAVE_RAMPY__