--- a/gcc/doc/fragments.texi	Sun Aug 21 07:07:55 2011 +0900
+++ b/gcc/doc/fragments.texi	Fri Oct 27 22:46:09 2017 +0900
@@ -1,5 +1,4 @@
-@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-@c 1999, 2000, 2001, 2003, 2004, 2005, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2017 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
@@ -49,29 +48,6 @@
 A list of source file names to be compiled or assembled and inserted
 into @file{libgcc.a}.
 
-@findex Floating Point Emulation
-@item Floating Point Emulation
-To have GCC include software floating point libraries in @file{libgcc.a}
-define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
-@smallexample
-# We want fine grained libraries, so use the new code
-# to build the floating point emulation libraries.
-FPBIT = fp-bit.c
-DPBIT = dp-bit.c
-
-
-fp-bit.c: $(srcdir)/config/fp-bit.c
-        echo '#define FLOAT' > fp-bit.c
-        cat $(srcdir)/config/fp-bit.c >> fp-bit.c
-
-dp-bit.c: $(srcdir)/config/fp-bit.c
-        cat $(srcdir)/config/fp-bit.c > dp-bit.c
-@end smallexample
-
-You may need to provide additional #defines at the beginning of @file{fp-bit.c}
-and @file{dp-bit.c} to control target endianness and other options.
-
-
 @findex CRTSTUFF_T_CFLAGS
 @item CRTSTUFF_T_CFLAGS
 Special flags used when compiling @file{crtstuff.c}.
@@ -115,6 +91,12 @@
 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
 as spaces.
 
+@code{MULTILIB_DIRNAMES} describes the multilib directories using GCC
+conventions and is applied to directories that are part of the GCC
+installation.  When multilib-enabled, the compiler will add a
+subdirectory of the form @var{prefix}/@var{multilib} before each
+directory in the search path for libraries and crt files.
+
 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
 @samp{m68000 m68020 msoft-float}.  You may specify a different value if
@@ -143,6 +125,61 @@
 *mthumb/*mhard-float*
 @end smallexample
 
+@findex MULTILIB_REQUIRED
+@item MULTILIB_REQUIRED
+Sometimes when there are only a few combinations are required, it would
+be a big effort to come up with a @code{MULTILIB_EXCEPTIONS} list to
+cover all undesired ones.  In such a case, just listing all the required
+combinations in @code{MULTILIB_REQUIRED} would be more straightforward.
+
+The way to specify the entries in @code{MULTILIB_REQUIRED} is same with
+the way used for @code{MULTILIB_EXCEPTIONS}, only this time what are
+required will be specified.  Suppose there are multiple sets of
+@code{MULTILIB_OPTIONS} and only two combinations are required, one
+for ARMv7-M and one for ARMv7-R with hard floating-point ABI and FPU, the
+@code{MULTILIB_REQUIRED} can be set to:
+@smallexample
+@code{MULTILIB_REQUIRED} =  mthumb/march=armv7-m
+@code{MULTILIB_REQUIRED} += march=armv7-r/mfloat-abi=hard/mfpu=vfpv3-d16
+@end smallexample
+
+The @code{MULTILIB_REQUIRED} can be used together with
+@code{MULTILIB_EXCEPTIONS}.  The option combinations generated from
+@code{MULTILIB_OPTIONS} will be filtered by @code{MULTILIB_EXCEPTIONS}
+and then by @code{MULTILIB_REQUIRED}.
+
+@findex MULTILIB_REUSE
+@item MULTILIB_REUSE
+Sometimes it is desirable to reuse one existing multilib for different
+sets of options.  Such kind of reuse can minimize the number of multilib
+variants.  And for some targets it is better to reuse an existing multilib
+than to fall back to default multilib when there is no corresponding multilib.
+This can be done by adding reuse rules to @code{MULTILIB_REUSE}.
+
+A reuse rule is comprised of two parts connected by equality sign.  The left
+part is the option set used to build multilib and the right part is the option
+set that will reuse this multilib.  Both parts should only use options
+specified in @code{MULTILIB_OPTIONS} and the equality signs found in options
+name should be replaced with periods.  An explicit period in the rule can be
+escaped by preceding it with a backslash.  The order of options in the left
+part matters and should be same with those specified in
+@code{MULTILIB_REQUIRED} or aligned with the order in @code{MULTILIB_OPTIONS}.
+There is no such limitation for options in the right part as we don't build
+multilib from them.
+
+@code{MULTILIB_REUSE} is different from @code{MULTILIB_MATCHES} in that it
+sets up relations between two option sets rather than two options.  Here is an
+example to demo how we reuse libraries built in Thumb mode for applications built
+in ARM mode:
+@smallexample
+@code{MULTILIB_REUSE} = mthumb/march.armv7-r=marm/march.armv7-r
+@end smallexample
+
+Before the advent of @code{MULTILIB_REUSE}, GCC select multilib by comparing command
+line options with options used to build multilib.  The @code{MULTILIB_REUSE} is
+complementary to that way.  Only when the original comparison matches nothing it will
+work to see if it is OK to reuse some existing multilib.
+
 @findex MULTILIB_EXTRA_OPTS
 @item MULTILIB_EXTRA_OPTS
 Sometimes it is desirable that when building multiple versions of
@@ -151,11 +188,59 @@
 of options to be used for all builds.  If you set this, you should
 probably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it.
 
-@findex NATIVE_SYSTEM_HEADER_DIR
-@item NATIVE_SYSTEM_HEADER_DIR
-If the default location for system headers is not @file{/usr/include},
-you must set this to the directory containing the headers.  This value
-should match the value of the @code{SYSTEM_INCLUDE_DIR} macro.
+@findex MULTILIB_OSDIRNAMES
+@item MULTILIB_OSDIRNAMES
+If @code{MULTILIB_OPTIONS} is used, this variable specifies 
+a list of subdirectory names, that are used to modify the search
+path depending on the chosen multilib.  Unlike @code{MULTILIB_DIRNAMES},
+@code{MULTILIB_OSDIRNAMES} describes the multilib directories using
+operating systems conventions, and is applied to the directories such as
+@code{lib} or those in the @env{LIBRARY_PATH} environment variable.
+The format is either the same as of
+@code{MULTILIB_DIRNAMES}, or a set of mappings.  When it is the same
+as @code{MULTILIB_DIRNAMES}, it describes the multilib directories
+using operating system conventions, rather than GCC conventions.  When it is a set
+of mappings of the form @var{gccdir}=@var{osdir}, the left side gives
+the GCC convention and the right gives the equivalent OS defined
+location.  If the @var{osdir} part begins with a @samp{!},
+GCC will not search in the non-multilib directory and use
+exclusively the multilib directory.  Otherwise, the compiler will
+examine the search path for libraries and crt files twice; the first
+time it will add @var{multilib} to each directory in the search path,
+the second it will not.
+
+For configurations that support both multilib and multiarch,
+@code{MULTILIB_OSDIRNAMES} also encodes the multiarch name, thus
+subsuming @code{MULTIARCH_DIRNAME}.  The multiarch name is appended to
+each directory name, separated by a colon (e.g.
+@samp{../lib32:i386-linux-gnu}).
+
+Each multiarch subdirectory will be searched before the corresponding OS
+multilib directory, for example @samp{/lib/i386-linux-gnu} before
+@samp{/lib/../lib32}.  The multiarch name will also be used to modify the
+system header search path, as explained for @code{MULTIARCH_DIRNAME}.
+
+@findex MULTIARCH_DIRNAME
+@item MULTIARCH_DIRNAME
+This variable specifies the multiarch name for configurations that are
+multiarch-enabled but not multilibbed configurations.
+
+The multiarch name is used to augment the search path for libraries, crt
+files and system header files with additional locations.  The compiler
+will add a multiarch subdirectory of the form
+@var{prefix}/@var{multiarch} before each directory in the library and
+crt search path.  It will also add two directories
+@code{LOCAL_INCLUDE_DIR}/@var{multiarch} and
+@code{NATIVE_SYSTEM_HEADER_DIR}/@var{multiarch}) to the system header
+search path, respectively before @code{LOCAL_INCLUDE_DIR} and
+@code{NATIVE_SYSTEM_HEADER_DIR}.
+
+@code{MULTIARCH_DIRNAME} is not used for configurations that support
+both multilib and multiarch.  In that case, multiarch names are encoded
+in @code{MULTILIB_OSDIRNAMES} instead.
+
+More documentation about multiarch can be found at
+@uref{https://wiki.debian.org/Multiarch}.
 
 @findex SPECS
 @item SPECS