doc: Add multilib section to CPU supplement

Add multilib section for ARM and PowerPC

3 files changed, 121 insertions, 0 deletions

diff --git a/doc/cpu_supplement/arm.t b/doc/cpu_supplement/arm.t
index 5dacbc0e73..012728cdb0 100644
--- a/doc/cpu_supplement/arm.t
+++ b/doc/cpu_supplement/arm.t
@@ -52,6 +52,63 @@ The following floating point units are supported.
 
 @end itemize
 
+@c
+@c
+@c
+@section Multilibs
+
+The following multilibs are available:
+
+@enumerate
+@item @code{.}: ARMv4T, ARM instruction set
+@item @code{thumb}: ARMv4T, Thumb-1 instruction set
+@item @code{thumb/armv6-m}: ARMv6M, subset of Thumb-2 instruction set
+@item @code{thumb/armv7-a}: ARMv7-A, Thumb-2 instruction set
+@item @code{thumb/armv7-a/neon/hard}: ARMv7-A, Thumb-2 instruction set with
+hard-float ABI Neon and VFP-D32 support
+@item @code{thumb/armv7-r}: ARMv7-R, Thumb-2 instruction set
+@item @code{thumb/armv7-r/vfpv3-d16/hard}: ARMv7-R, Thumb-2 instruction set
+with hard-float ABI VFP-D16 support
+@item @code{thumb/armv7-m}: ARMv7-M, Thumb-2 instruction set with hardware
+integer division (SDIV/UDIV)
+@item @code{thumb/armv7-m/fpv4-sp-d16}: ARMv7-M, Thumb-2 instruction set with
+hardware integer division (SDIV/UDIV) and hard-float ABI FPv4-SP support
+@item @code{eb/thumb/armv7-r}: ARMv7-R, Big-endian Thumb-2 instruction set
+@item @code{eb/thumb/armv7-r/vfpv3-d16/hard}: ARMv7-R, Big-endian Thumb-2
+instruction set with hard-float ABI VFP-D16 support
+@end enumerate
+
+Multilib 1. and 2. support the standard ARM7TDMI and ARM926EJ-S targets.
+
+Multilib 3. supports the Cortex-M0 and Cortex-M1 cores.
+
+Multilib 8. supports the Cortex-M3 and Cortex-M4 cores, which have a special
+hardware integer division instruction (this is not present in the A and R
+profiles).
+
+Multilib 9. supports the Cortex-M4 cores with a floating point unit.
+
+Multilib 4. and 5. support the Cortex-A processors.
+
+Multilib 6., 7., 10. and 11. support the Cortex-R processors.  Here also
+big-endian variants are available.
+
+Use for example the following GCC options
+
+@example
+-mthumb -march=armv7-a -mfpu=neon -mfloat-abi=hard -mtune=cortex-a9
+@end example
+
+to build an application or BSP for the ARMv7-A architecture and tune the code
+for a Cortex-A9 processor.  It is important to select the options used for the
+multilibs. For example
+
+@example
+-mthumb -mcpu=cortex-a9
+@end example
+
+alone will not select the ARMv7-A multilib.
+
 @section Calling Conventions
 
 Please refer to the
diff --git a/doc/cpu_supplement/general.t b/doc/cpu_supplement/general.t
index 3d84c2a901..82b8dcbbd4 100644
--- a/doc/cpu_supplement/general.t
+++ b/doc/cpu_supplement/general.t
@@ -102,6 +102,36 @@ the FP software emulation will be context switched.
 @c
 @c
 @c
+@section Multilibs
+
+Newlib and GCC provide several target libraries like the @file{libc.a},
+@file{libm.a} and @file{libgcc.a}.  These libraries are artifacts of the GCC
+build process.  Newlib is built together with GCC.  To provide optimal support
+for various chip derivatives and instruction set revisions multiple variants of
+these libraries are available for each architecture.  For example one set may
+use software floating point support and another set may use hardware floating
+point instructions.  These sets of libraries are called @emph{multilibs}.  Each
+library set corresponds to an application binary interface (ABI) and
+instruction set.
+
+A multilib variant can be usually detected via built-in compiler defines at
+compile-time.  This mechanism is used by RTEMS to select for example the
+context switch support for a particular BSP.  The built-in compiler defines
+corresponding to multilibs are the only architecture specific defines allowed
+in the @code{cpukit} area of the RTEMS sources.
+
+Invoking the GCC with the @code{-print-multi-lib} option lists the available
+multilibs.  Each line of the output describes one multilib variant.  The
+default variant is denoted by @code{.} which is selected when no or
+contradicting GCC machine options are selected.  The multilib selection for a
+target is specified by target makefile fragments (see file @file{t-rtems} in
+the GCC sources and section
+@uref{https://gcc.gnu.org/onlinedocs/gccint/Target-Fragment.html#Target-Fragment,The Target Makefile Fragment}
+in the @uref{https://gcc.gnu.org/onlinedocs/gccint/,GCC Internals Manual}.
+
+@c
+@c
+@c
 @section Calling Conventions
 
 Each high-level language compiler generates subroutine entry and exit
diff --git a/doc/cpu_supplement/powerpc.t b/doc/cpu_supplement/powerpc.t
index 95a6315f15..abf02e07d9 100644
--- a/doc/cpu_supplement/powerpc.t
+++ b/doc/cpu_supplement/powerpc.t
@@ -181,6 +181,40 @@ the PPC603e.
 @c
 @c
 @c
+@section Multilibs
+
+The following multilibs are available:
+
+@enumerate
+@item @code{.}: 32-bit PowerPC with FPU
+@item @code{nof}: 32-bit PowerPC with software floating point support
+@item @code{m403}: Instruction set for PPC403 with FPU
+@item @code{m505}: Instruction set for MPC505 with FPU
+@item @code{m603e}: Instruction set for MPC603e with FPU
+@item @code{m603e/nof}: Instruction set for MPC603e with software floating
+point support
+@item @code{m604}: Instruction set for MPC604 with FPU
+@item @code{m604/nof}: Instruction set for MPC604 with software floating point
+support
+@item @code{m860}: Instruction set for MPC860 with FPU
+@item @code{m7400}: Instruction set for MPC7500 with FPU
+@item @code{m7400/nof}: Instruction set for MPC7500 with software floating
+point support
+@item @code{m8540}: Instruction set for e200, e500 and e500v2 cores with
+single-precision FPU and SPE
+@item @code{m8540/gprsdouble}: Instruction set for e200, e500 and e500v2 cores
+with double-precision FPU and SPE
+@item @code{m8540/nof/nospe}: Instruction set for e200, e500 and e500v2 cores
+with software floating point support and no SPE
+@item @code{me6500/m32}: 32-bit instruction set for e6500 core with FPU and
+AltiVec
+@item @code{me6500/m32/nof/noaltivec}: 32-bit instruction set for e6500 core
+with software floating point support and no AltiVec
+@end enumerate
+
+@c
+@c
+@c
 
 @section Calling Conventions