[RFA:] Adjust documentation for LEGITIMATE_CONSTANT_P et al to match reality, take 2

[Hans-Peter Nilsson <hans-peter dot nilsson at axis dot com>]

See the thread at
<http://gcc.gnu.org/ml/gcc-patches/2008-09/msg00552.html>.  This
update merges, with a single s/code/type/ for CONSTANT_P, mine
and Paolo Bonzini's attempts and hopefully addresses most of
Richard Sandiford's objections.  I hope most agree this is a
reasonable step forward and that the discontented not see it as
a step backward.

Tested "make info-gcc dvi-gcc" and inspected output *as well as messages*.
(Protocol says to check that the dvi warnings don't regress when you add
text, for new chapters that often happens.)

Ok to commit?

	* doc/tm.texi (Addressing Modes) <CONSTANT_ADDRESS_P>: Recommend
	using CONSTANT_P in conjunction with CONST contents test.
	<CONSTANT_P, GO_IF_LEGITIMATE_ADDRESS, LEGITIMATE_CONSTANT_P>:
	Ditto.
	(PIC) <LEGITIMATE_PIC_OPERAND_P>: Remove sentence advising to
	leave undefined in the rare special case of all constants being
	valid.

Index: doc/tm.texi
===================================================================
--- doc/tm.texi	(revision 140538)
+++ doc/tm.texi	(working copy)
@@ -5267,17 +5267,23 @@ post-address side-effect generation invo
 
 @defmac CONSTANT_ADDRESS_P (@var{x})
 A C expression that is 1 if the RTX @var{x} is a constant which
-is a valid address.  On most machines, this can be defined as
-@code{CONSTANT_P (@var{x})}, but a few machines are more restrictive
-in which constant addresses are supported.
+is a valid address.  A port can use @code{CONSTANT_P (@var{x})} to
+simplify the expression, but must always validize the contents of
+a @code{CONST} expression.
 @end defmac
 
 @defmac CONSTANT_P (@var{x})
 @code{CONSTANT_P}, which is defined by target-independent code,
-accepts integer-values expressions whose values are not explicitly
+accepts integer-valued expressions whose values are not explicitly
 known, such as @code{symbol_ref}, @code{label_ref}, and @code{high}
 expressions and @code{const} arithmetic expressions, in addition to
 @code{const_int} and @code{const_double} expressions.
+This macro only checks the type of the @var{x} rtx; it does not
+ensure that the target supports using @var{x} as an immediate
+value or as a literal data constant.  In particular, the target
+might use a constant pool for large constants or might split them,
+or @var{x} might be a @code{CONST} wrapping an expression that is
+not valid for the target.
 @end defmac
 
 @defmac MAX_REGS_PER_ADDRESS
@@ -5321,9 +5327,8 @@ levels of macros may be the same whether
 
 Normally, constant addresses which are the sum of a @code{symbol_ref}
 and an integer are stored inside a @code{const} RTX to mark them as
-constant.  Therefore, there is no need to recognize such sums
-specifically as legitimate addresses.  Normally you would simply
-recognize any @code{const} as legitimate.
+constant, but this is not always the case.  Therefore, you need to
+validize such expressions as legitimate addresses.
 
 Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant
 sums that are not marked with  @code{const}.  It assumes that a naked
@@ -5457,9 +5462,8 @@ You may assume that @var{addr} is a vali
 @defmac LEGITIMATE_CONSTANT_P (@var{x})
 A C expression that is nonzero if @var{x} is a legitimate constant for
 an immediate operand on the target machine.  You can assume that
-@var{x} satisfies @code{CONSTANT_P}, so you need not check this.  In fact,
-@samp{1} is a suitable definition for this macro on machines where
-anything @code{CONSTANT_P} is valid.
+@var{x} satisfies @code{CONSTANT_P}, so you need not check this, but
+you need to validize @code{CONST} expressions.
 @end defmac
 
 @deftypefn {Target Hook} rtx TARGET_DELEGITIMIZE_ADDRESS (rtx @var{x})
@@ -6806,9 +6810,7 @@ A C expression that is nonzero if @var{x
 operand on the target machine when generating position independent code.
 You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not
 check this.  You can also assume @var{flag_pic} is true, so you need not
-check it either.  You need not define this macro if all constants
-(including @code{SYMBOL_REF}) can be immediate operands when generating
-position independent code.
+check it either.
 @end defmac
 
 @node Assembler Format

brgds, H-P