wiki:Developer/Multilib

Version 7 (modified by Ralph Holmes, on Jan 3, 2016 at 5:32:35 PM) (diff)

Fix spelling and/or grammar.

Multilib RTEMS

The multilib process supports building a set of related libraries for a given target where the individual libraries in the set use different specific compiler flags (such as flags for code generation options, pre-processor defines, etc) for the individual libraries. The reason this is needed can be seen by examining the M68K GCC compiler. That compiler generates code for a number of processor variants in the M68K family, for example, it can generate code for the original 68000, the 68040 or a 528x Coldfire. These processors all use a closely related instruction set, but processor differences mean code compiled for one may not run on another. GCC provides a special library called libgcc.a that holds intrinsic functions needed by the compiler. These intrinsic functions provide "software instructions" (such as non-basic math support routines) that the processor may not support. However, which functions GCC considers to be intrinsic should be able to vary within a processor family. One processor variant will have hardware floating point and another processor variant will not, and GCC (and RTEMS) should be able to generate efficient code for each processor variant. When we wish to have different code for a range of related yet potentially incompatible processors in a family by providing multiple related libraries we use the multilib process.

The multilib process extends beyond libgcc.a to libc.a, libm.a, and libstd++.a. An RTEMS tool set will provide each of these libraries for each of the processor variants that GCC supports. You can see the multilib information by invoking gcc with the option '-print-multi-lib'. The output for the M68K tool chain is -

$ m68k-rtems-gcc -print-multi-lib .; m68000;@m68000 m5200;@m5200 m5206e;@m5206e m528x;@m528x m5307;@m5307 m5407;@m5407 mcpu32;@mcpu32 m68040;@m68040 m68060;@m68060 msoft-float;@msoft-float

This output is not easy to read as it is designed for other tools or packages.

RTEMS core under the cpukit source tree does not reference any BSP specific details. This allows it to be built as a set of multiple libraries named librtemscpu.a. A configure command line option will build a multilib RTEMS as shown in Building a CPU Kit.

BSP and CPU model specific portions of RTEMS (libcpu and libbsp) are built into the separate library librtemsbsp.a.

RTEMS Multilib Selections

The range of variants a specific tool set creates can vary for the same processor family. For example a build of the M68K tool set for m68k-elf can create a different variant set compared to the RTEMS tool set built with m68k-rtems. RTEMS tries to keep the number of libraries built to a minimum to keep the build time down, the amount of disk space used, and avoid a variant explosion that could result if a specific processor has a large number of variants. The Coldfire is a good example of this.

Adding a new multilib variant only makes sense if -

  • Some code is being compiled specifically for a specific variant. An example would be newlib, libgcc or RTEMS/cpukit containing code conditionally being compiled upon a specific processor, i.e. for the Coldfire family of processors "#ifdef mcf528x".
  • GCC using an ISA not compatible to one already being present.
  • GCC using an optimization that is measurably superior than to others.

If one of these criteria is met then a new processor variant may be considered.

In some legitimate cases, RTEMS needs to know information about a specific CPU model which is beyond the multilib variations. This may be due to issues such as cache size, peripherals on the CPU itself, or interrupt vectoring specifics. In these cases, the code in question should be placed in the libcpu or libbsp source where the specific CPU model is available for use.

On some ports, code that is normally found under cpukit/score/cpu is placed under libcpu or libbsp/CPU/shared because it requires knowing the specific CPU model to properly implement. This is an unfortunate fact of life which makes it hard to find source sometimes.

Building a CPU Kit

Building a CPU Kit for a specific tool chain results in RTEMS being built for each one of the processor variants supported by the tool chain. This will increase the time it takes to build RTEMS, but does mean RTEMS will not need to be built for the tool chain again regardless of the number of board support packages to be built. This is not suitable for the development and maintance of RTEMS. It does help:

  • Control of RTEMS while allowing teams BSP flexibility.
  • Binary packages for 3rd party distributions.

The BSP can be:

  • Part of the RTEMS source tree,
  • A separate package (a separate library),
  • Built into the application.

Which type of BSP depends on where and how you use RTEMS and the type of hardware you use. If the target hardware is a common available platform placing the BSP in RTEMS is encouraged as others can share the work and aid fixing bugs.

If the target hardware is custom built for a specific purpose placing that BSP into the RTEMS is not of great value unless it is the only one of that type for that processor and would make a good reference BSP. Making a separate BSP allows target hardware to be shared between applications. This is great for custom hardware a company uses in a number of products.

Finally the BSP can be built into the application. This allows a separation from the released RTEMS sources, which has a slow release cycle, and a BSP specific to an application that has tight configuration control and verification and validation requirements.

There can be little difference between BSP code base or it can be very different. A BSP separated from RTEMS does not require the BSP be merged and updated to work with a newer RTEMS release. RTEMS is always changing and evolving and RTEMS maintainers need the freedom to make changes that best suit RTEMS. On the other hand separate BSPs code not get to share common BSP code in RTEMS. The same extends to libchip drivers.

The command line to build a CPU Kit for the M68K target can be -

$ ../rtems/configure --target=m68k-rtems4.7 \

--enable-multilib \ --enable-doc \ --enable-cxx \ --enable-posix \ --enable-networking \ --disable-tests \ --disable-itron \ --prefix=/opt/rtems-4.7

You will need to select the <tt>configure</tt> options that suite you. To build RTEMS enter -

$ make RTEMS_BSP= all install

Building an External BSP

Once you have a CPU Kit install you can build a BSP in the RTEMS source tree by using the following -

$ rm -rf ../rtems/cpukit $ ../rtems/configure --target=m68k-rtems4.7 \

--prefix=/opt/rtems-4.7

$ make RTEMS_BSP=uC5282