[PATCH] doc: Add multilib section to CPU supplement

[Sebastian Huber]

Add multilib section for ARM and PowerPC
---
 doc/cpu_supplement/arm.t     | 57 ++++++++++++++++++++++++++++++++++++++++++++
 doc/cpu_supplement/general.t | 30 +++++++++++++++++++++++
 doc/cpu_supplement/powerpc.t | 34 ++++++++++++++++++++++++++
 3 files changed, 121 insertions(+)

diff --git a/doc/cpu_supplement/arm.t b/doc/cpu_supplement/arm.t
index 5dacbc0..012728c 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
 
+ at c
+ at c
+ at c
+ at section Multilibs
+
+The following multilibs are available:
+
+ at enumerate
+ at item @code{.}: ARMv4T, ARM instruction set
+ at item @code{thumb}: ARMv4T, Thumb-1 instruction set
+ at item @code{thumb/armv6-m}: ARMv6M, subset of Thumb-2 instruction set
+ at item @code{thumb/armv7-a}: ARMv7-A, Thumb-2 instruction set
+ at item @code{thumb/armv7-a/neon/hard}: ARMv7-A, Thumb-2 instruction set with
+hard-float ABI Neon and VFP-D32 support
+ at item @code{thumb/armv7-r}: ARMv7-R, Thumb-2 instruction set
+ at item @code{thumb/armv7-r/vfpv3-d16/hard}: ARMv7-R, Thumb-2 instruction set
+with hard-float ABI VFP-D16 support
+ at item @code{thumb/armv7-m}: ARMv7-M, Thumb-2 instruction set with hardware
+integer division (SDIV/UDIV)
+ at 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
+ at item @code{eb/thumb/armv7-r}: ARMv7-R, Big-endian Thumb-2 instruction set
+ at item @code{eb/thumb/armv7-r/vfpv3-d16/hard}: ARMv7-R, Big-endian Thumb-2
+instruction set with hard-float ABI VFP-D16 support
+ at 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
+
+ at example
+-mthumb -march=armv7-a -mfpu=neon -mfloat-abi=hard -mtune=cortex-a9
+ at 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
+
+ at example
+-mthumb -mcpu=cortex-a9
+ at 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 3d84c2a..1cfb475 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
+ at section Multilibs
+
+Newlib and GCC provide several target libraries like the @file{libc.a},
+ at file{libm.a} and @file{libgcc.a}.  These libraries are artifacts of the GCC
+build process.  Newlib is build 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.
+
+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
+ at 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}.
+
+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.
+
+ at c
+ at c
+ at 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 95a6315..abf02e0 100644
--- a/doc/cpu_supplement/powerpc.t
+++ b/doc/cpu_supplement/powerpc.t
@@ -181,6 +181,40 @@ the PPC603e.
 @c
 @c
 @c
+ at section Multilibs
+
+The following multilibs are available:
+
+ at enumerate
+ at item @code{.}: 32-bit PowerPC with FPU
+ at item @code{nof}: 32-bit PowerPC with software floating point support
+ at item @code{m403}: Instruction set for PPC403 with FPU
+ at item @code{m505}: Instruction set for MPC505 with FPU
+ at item @code{m603e}: Instruction set for MPC603e with FPU
+ at item @code{m603e/nof}: Instruction set for MPC603e with software floating
+point support
+ at item @code{m604}: Instruction set for MPC604 with FPU
+ at item @code{m604/nof}: Instruction set for MPC604 with software floating point
+support
+ at item @code{m860}: Instruction set for MPC860 with FPU
+ at item @code{m7400}: Instruction set for MPC7500 with FPU
+ at item @code{m7400/nof}: Instruction set for MPC7500 with software floating
+point support
+ at item @code{m8540}: Instruction set for e200, e500 and e500v2 cores with
+single-precision FPU and SPE
+ at item @code{m8540/gprsdouble}: Instruction set for e200, e500 and e500v2 cores
+with double-precision FPU and SPE
+ at item @code{m8540/nof/nospe}: Instruction set for e200, e500 and e500v2 cores
+with software floating point support and no SPE
+ at item @code{me6500/m32}: 32-bit instruction set for e6500 core with FPU and
+AltiVec
+ at item @code{me6500/m32/nof/noaltivec}: 32-bit instruction set for e6500 core
+with software floating point support and no AltiVec
+ at end enumerate
+
+ at c
+ at c
+ at c
 
 @section Calling Conventions
 
-- 
1.8.4.5