[PATCH] doc: Add multilib section to CPU supplement

Mon Dec 15 17:37:31 UTC 2014

Great! "multilib" stuff is very confusing for a new developer. The
added documentation is nice. I suggest 2 changes below. I only read
general.t changes.

On Mon, Dec 15, 2014 at 9:35 AM, Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
> 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
s/is build/is built/

> +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.
I would move this last paragraph up to before the previous one.

> +
> + 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
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel