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,
