[PATCH 1/8] [RS6000] rs6000_rtx_costs comment

[Alan Modra <amodra@gmail.com>]

This lays out the ground rules for following patches.

	* config/rs6000/rs6000.c (rs6000_rtx_costs): Expand comment.

diff --git a/gcc/config/rs6000/rs6000.c b/gcc/config/rs6000/rs6000.c
index b58eeae2b98..97180bb3819 100644
--- a/gcc/config/rs6000/rs6000.c
+++ b/gcc/config/rs6000/rs6000.c
@@ -21208,7 +21208,46 @@ rs6000_cannot_copy_insn_p (rtx_insn *insn)
 
 /* Compute a (partial) cost for rtx X.  Return true if the complete
    cost has been computed, and false if subexpressions should be
-   scanned.  In either case, *TOTAL contains the cost result.  */
+   scanned.  In either case, *TOTAL contains the cost result.
+
+   1) Calls from places like optabs.c:avoid_expensive_constant will
+   come here with OUTER_CODE set to an operation such as AND with X
+   being a CONST_INT or other CONSTANT_P type.  This will be compared
+   against set_src_cost, where we'll come here with OUTER_CODE as SET
+   and X the same constant.
+
+   2) Calls from places like combine.c:distribute_and_simplify_rtx are
+   asking whether a possibly quite complex SET_SRC can be implemented
+   more cheaply than some other logically equivalent SET_SRC.
+
+   3) Calls from places like ifcvt.c:default_noce_conversion_profitable_p
+   will come here via seq_cost which calls set_rtx_cost on single set
+   insns.  set_rtx_cost passes the pattern of a SET insn in X with
+   OUTER_CODE as INSN.  The overall cost should be comparable to
+   rs6000_insn_cost since the code is comparing one insn sequence
+   (some of which may be costed by insn_cost) against another sequence.
+   Note the difference between set_rtx_cost, which costs the entire
+   SET, and set_src_cost, which costs just the SET_SRC.
+
+   4) Calls from places like cprop.c:try_replace_reg will also come
+   here via set_rtx_cost, with X either a valid pattern of a SET or
+   one where some registers have been replaced with constants.  The
+   replacements may make the SET invalid, for example if
+     (set (reg1) (and (reg2) (const_int 0xfff)))
+   has reg2 replaced as
+     (set (reg1) (and (symbol_ref) (const_int 0xfff)))
+   then the replacement can't be implemented in one instruction and
+   really the cost should be higher by one instruction.  However,
+   the cost for invalid insns doesn't matter much except that a
+   higher cost may lead to their rejection earlier.
+
+   5) fwprop.c:should_replace_address puts yet another wrinkle on this
+   function, where we prefer an address calculation that is more
+   complex yet has the same address_cost.  In this case "more
+   complex" is determined by having a higher set_src_cost.  So for
+   example, if we want a plain (reg) address to be replaced with
+   (plus (reg) (const)) when possible then PLUS needs to cost more
+   than zero here.  */
 
 static bool
 rs6000_rtx_costs (rtx x, machine_mode mode, int outer_code,