-Each pseudo-register has a natural mode. If it is necessary to
-operate on it in a different mode---for example, to perform a fullword
-move instruction on a pseudo-register that contains a single
-byte---the pseudo-register must be enclosed in a @code{subreg}. In
-such a case, @var{bytenum} is zero.
-
-Usually @var{m} is at least as narrow as the mode of @var{reg}, in which
-case it is restricting consideration to only the bits of @var{reg} that
-are in @var{m}.
-
-Sometimes @var{m} is wider than the mode of @var{reg}. These
-@code{subreg} expressions are often called @dfn{paradoxical}. They are
-used in cases where we want to refer to an object in a wider mode but do
-not care what value the additional bits have. The reload pass ensures
-that paradoxical references are only made to hard registers.
-
-The other use of @code{subreg} is to extract the individual registers of
-a multi-register value. Machine modes such as @code{DImode} and
-@code{TImode} can indicate values longer than a word, values which
-usually require two or more consecutive registers. To access one of the
-registers, use a @code{subreg} with mode @code{SImode} and a
-@var{bytenum} offset that says which register.
-
-Storing in a non-paradoxical @code{subreg} has undefined results for
-bits belonging to the same word as the @code{subreg}. This laxity makes
-it easier to generate efficient code for such instructions. To
-represent an instruction that preserves all the bits outside of those in
-the @code{subreg}, use @code{strict_low_part} around the @code{subreg}.
+Each pseudo register has a natural mode. If it is necessary to
+operate on it in a different mode, the register must be
+enclosed in a @code{subreg}.
+
+There are currently three supported types for the first operand of a
+@code{subreg}:
+@itemize
+@item pseudo registers
+This is the most common case. Most @code{subreg}s have pseudo
+@code{reg}s as their first operand.
+
+@item mem
+@code{subreg}s of @code{mem} were common in earlier versions of GCC and
+are still supported. During the reload pass these are replaced by plain
+@code{mem}s. On machines that do not do instruction scheduling, use of
+@code{subreg}s of @code{mem} are still used, but this is no longer
+recommended. Such @code{subreg}s are considered to be
+@code{register_operand}s rather than @code{memory_operand}s before and
+during reload. Because of this, the scheduling passes cannot properly
+schedule instructions with @code{subreg}s of @code{mem}, so for machines
+that do scheduling, @code{subreg}s of @code{mem} should never be used.
+To support this, the combine and recog passes have explicit code to
+inhibit the creation of @code{subreg}s of @code{mem} when
+@code{INSN_SCHEDULING} is defined.
+
+The use of @code{subreg}s of @code{mem} after the reload pass is an area
+that is not well understood and should be avoided. There is still some
+code in the compiler to support this, but this code has possibly rotted.
+This use of @code{subreg}s is discouraged and will most likely not be
+supported in the future.
+
+@item hard registers
+It is seldom necessary to wrap hard registers in @code{subreg}s; such
+registers would normally reduce to a single @code{reg} rtx. This use of
+@code{subreg}s is discouraged and may not be supported in the future.
+
+@end itemize
+
+@code{subreg}s of @code{subreg}s are not supported. Using
+@code{simplify_gen_subreg} is the recommended way to avoid this problem.
+
+@code{subreg}s come in two distinct flavors, each having its own
+usage and rules:
+
+@table @asis
+@item Paradoxical subregs
+When @var{m1} is strictly wider than @var{m2}, the @code{subreg}
+expression is called @dfn{paradoxical}. The canonical test for this
+class of @code{subreg} is:
+
+@smallexample
+GET_MODE_SIZE (@var{m1}) > GET_MODE_SIZE (@var{m2})
+@end smallexample
+
+Paradoxical @code{subreg}s can be used as both lvalues and rvalues.
+When used as an lvalue, the low-order bits of the source value
+are stored in @var{reg} and the high-order bits are discarded.
+When used as an rvalue, the low-order bits of the @code{subreg} are
+taken from @var{reg} while the high-order bits may or may not be
+defined.
+
+The high-order bits of rvalues are in the following circumstances:
+
+@itemize
+@item @code{subreg}s of @code{mem}
+When @var{m2} is smaller than a word, the macro @code{LOAD_EXTEND_OP},
+can control how the high-order bits are defined.
+
+@item @code{subreg} of @code{reg}s
+The upper bits are defined when @code{SUBREG_PROMOTED_VAR_P} is true.
+@code{SUBREG_PROMOTED_UNSIGNED_P} describes what the upper bits hold.
+Such subregs usually represent local variables, register variables
+and parameter pseudo variables that have been promoted to a wider mode.
+
+@end itemize
+
+@var{bytenum} is always zero for a paradoxical @code{subreg}, even on
+big-endian targets.
+
+For example, the paradoxical @code{subreg}:
+
+@smallexample
+(set (subreg:SI (reg:HI @var{x}) 0) @var{y})
+@end smallexample