Installing, Configuring and Porting XFLAT Shared Libraries

<<Index>>

• Installing XFLAT Shared Libraries in the Toolchain
• Installing XFLAT Shared Libraries in the Target Filesystem
• Configuring XFLAT Shared Libraries
• Porting XFLAT Shared Libraries

Toolchain Independence - One of the features of the XFLAT support, however, is that it does not depend on specifics of the toolchain. In principle, the XFLAT shared library support should be usable without change to the ARM GNU toolchain. Extension to non-GNU, non-ARM toolchains is also possible, but not without some changes to the base code.

Build Script - The following is a snippet from the Cadenux toolchain build script. This snippet illustrates how the XFLAT shared library support is built and installed into the Cadenux ARM7 toolchain:

# remove build xflat directory if it exists
rm -rf ${BUILD_PREFIX}/build/xflat 2>/dev/null
mkdir -p ${BUILD_PREFIX}/build/xflat

# step a - prepare
# remove build xflat src directory if it exists
rm -rf ${BUILD_PREFIX}/src/xflat 2>/dev/null

# create the virgin xflat source tree
tar jxf ${XFLAT_DIR}/${XFLAT}-${XFLAT_VERSION}.tar.bz2 \
  -directory=${BUILD_PREFIX}/src || \
    { echo "tar of xflat failed" ; exit 1; }

# add patches to the virgin source tree
for i in ${XFLAT_PATCH}; do
  cat ${XFLAT_DIR}/$i | \
    patch -p0 -N -d ${BUILD_PREFIX}/src/${XFLAT} || \
      { echo "patch of xflat failed" ; exit 1; }
done

# step b - make
cd ${BUILD_PREFIX}/src/xflat || \
  { echo "cd failed" ; exit 1; }

make >${BUILD_PREFIX}/build/LOG.xflat.make 2>&1 || \
  { echo "Failed! See ${BUILD_PREFIX}/build/LOG.xflat.make" ; exit 1; }

# step c - install
make root_install >${BUILD_PREFIX}/build/LOG.xflat.install 2>&1 || \
  { echo "Failed! See ${BUILD_PREFIX}/build/LOG.flat.install" ; exit 1; }

Build Steps.

• Step a - prepare. All Cadenux tools are built using two directory structures: A build directory tree and source directory tree. Using separate build and source directory tress often facilitates building different variants from the same same source tree. The build structure for the XFLAT tools follows this convention. However, the build directory is not used.

  Both the build and source directories reside under a root directory structure identified as BUILD_PREFIX. For the Cadenux toolchain, BUILD_PREFIX is defined as:

  BUILD_PREFIX=/opt/Cadenux-build/${CADENUX_ARCH}/${CADENUX_KERNEL}/${CADENUX_KERNEL}
  

  For the DSC25 platform and the uClinux-2.0.x kernel, the XFLAT build and source directories resolve to:

  /opt/Cadenux-build/dsc25/uclinux-2.0/build/xflat
  

  and

  /opt/Cadenux-build/dsc25/src/xflat
  

  respectively.

  Given these definitions, preparation consists of:

  1. Removal of build directory, discarding the results of any previous build,
  2. Creation of a new build directory,
  3. Removal of the source directory, discarding and previous XFLAT versions,
  4. Creation of a new source directory by uncompressing the XFLAT tarball, and
  5. Application of any patches that may be necessary.

  At present, there are no patches to the XFLAT code. However, this mechanism may be used to support variants, intermediate versions, customizations, etc.

• Step b - make. Making the XFLAT toolchain consists simply in invoking the Makefile in the prepared XFLAT source directory.

  Notice that the output from the make is piped to ${BUILD_PREFIX}/build/LOG.xflat.make. In the event of any make failures, details of the failure should be found there.

• Step c - install. At the conclusion of a successful make, XFLAT binaries will be generated in the XFLAT source tree. The install step consists of copying these binaries into the correct locations in the toolchain.

  Installing the XFLAT toolchain consists in again invoking the Makefile in the prepared XFLAT source directory but for the root_install target. This will install the following files:

  SOURCE ${BUILD_PREFIX}/src/xflat/	DESTINATION /opt/Cadenux/${CADENUX_ARCH}/${CADENUX_KERNEL}/crossdev/	COMMENTS
  ./tools/ xflat-gcc	./arm-uclinux/bin/ xflat-gcc	See xflat-gcc description.
  ./tools/ xflat-ld	./arm-uclinux/bin/ xflat-ld	See xflat-ld description.
  ./tools/ readxflat	./arm-uclinux/bin/ readxflat	See readxflat description.
  ./tools/ ldelflib	./arm-uclinux/bin/ ldelflib	See ldelflib description.
  ./tools/ ldelf2xflt	./arm-uclinux/bin/ ldelf2xflt	See ldelf2xflt description.
  ./arch-include/ all files	./arm-uclinux/include/xflat/ all files	All of the header files in the arch-include subdirectory are copied into the compilers include/xflat directory.
  ./libc/ libc-xflat.so.1	./arm-uclinux/lib/ libc-xflat.so.1	This is the shared library found at: /opt/Cadenux/${CADENUX_ARCH}/${CADENUX_KERNEL}/crossdev/ arm-uclinux/libc.a re-packaged as a XFLAT shared library. In principle, this can be any libc. As of this writing, only uClibc-0.9.15 has been wrapped in this manner. A link to libc-xflat.so.1 is also installed so that the shared library can also be referenced with the name libc-xflat.so.
  ./libc/ crt0-xflat.o	./arm-uclinux/lib/ crt0-xflat.o	This is the XFLAT startup logic that will be included at the beginning of every XFLAT program that uses libc. This startup file is intended only for use with uClibc. Versions of libc other than 0.9.15 could require changes to this startup logic.
  ./tools/ crt0-nolibc.o	./arm-uclinux/lib/ crt0-nolibc.o	This is a special C startup file for C programs that do not use libc.
  ./binfmt/linux-2.0/ binfmt_xflat.o or, ./binfmt/linux-2.4/ binfmt_xflat.o	./arm-uclinux/lib/ binfmt_xflat.o	This is the kernel module that loads XFLAT binaries. There are two versions: One for uClinux-2.0.x and one for uClinux-2.4.x. This kernel module must be installed (using insmod) to add support for recognition and loading of XFLAT binaries. This is done automatically in the Cadenux BSP in the kernel startup scripts.
  ./ldso/xflat-ldso/ ld-xflat.so.1	./arm-uclinux/lib/ ld-xflat.so.1	This is the XFLAT dynamic loader. It is the logic that loads the XFLAT program and binds it to XFLAT shared libraries at runtime. A link to ld-xflat.so.1 is also installed so that the shared library can also be referenced with the name ld-xflat.so.
  ./xflat-user.ld	./arm-uclinux/lib/ xflat-user.ld	This is the linker script that should be used when building XFLAT modules.

  Notice that the output from the install is piped to ${BUILD_PREFIX}/build/LOG.xflat.install. In the event of any install failures, details of the failure should be found there.

<<Table of Contents>>
<<Index>>

When the target system is built in the Cadenux BSP, two target platform images are produced: One that that contains the kernel and one that contains the contents of a read-only file system. All application logic (including kernel modules) must be installed into the read-only file system image when the Cadenux BSP is built and before the file system image is loaded into the target machine flash memory. This file build process consists of several steps:

1. Creation of an copy of the target system file system on the host machine,
2. Copying of applications into the correct directories in the file system copy, then
3. Use of file-system-specific tools to convert the file system copy into something that can be loaded into, and used by, the target system.

In the preceding section, we saw that the installation of the XFLAT tool chain installed several ARM7 binaries into the Cadenux toolchain under /opt/Cadenux/${CADENUX_ARCH}/${CADENUX_KERNEL}/crossdev/arm-uclinux/lib. Subsequent installation of these XFLAT binaries into the target file system consists of copying these files from the tool lib directory into the target file system copy (during step #2 above). Here is the relevant snippet from the Cadenux BSP make logic:

@# Installing shared uClibc...
@install -D --mode=755 ${TOOL_LIBDIR}/ld-xflat.so.1 \
${FSROOT_DIR}/lib/ld-xflat.so.1 
@ln -sf ld-xflat.so.1 ${FSROOT_DIR}/lib/ld-xflat.so
@install -D --mode=755 ${TOOL_LIBDIR}/libc-xflat.so.1 \
${FSROOT_DIR}/lib/libc-xflat.so.1
@ln -sf libc-xflat.so.1 ${FSROOT_DIR}/lib/libc-xflat.so
@install -D --mode=755 ${TOOL_LIBDIR}/binfmt_xflat.o \
${FSROOT_DIR}/${KERNEL_MODULES}/binfmt_xflat.o

Where TOOL_DIR is the location in the Cadenux tool chain where the XFLAT binaries were stored (same as /opt/Cadenux/${CADENUX_ARCH}/${CADENUX_KERNEL}/crossdev/arm-uclinux/lib), ${FSROOT_DIR} is the location of the root of the target file system copy, and ${KERNEL_MODULES} is the directory that the kernel will expect to find kernel modules at runtime.

Note that only copies of the XFLAT dynamic loader (ld-xflat.so), the XFLAT kernel module (binfmt_xflat.o) and shared libraries (libc-xflat.so) need be copied in to the target file system copy.

<<Table of Contents>>
<<Index>>

The XFLAT shared library logic was designed as part of the Cadenux toolchain. For this reason, it does not have extensive configuration tools. However, all configuration logic has been extracted and retained in a single file: ARM7 shared library support can be configured for a customized installation by modifying the single file xflat/Make.defs. This "makefile fragment" is included by every Makefile in the XFLAT directory tree; any changes made here will effect the generation of all XFLAT code.

The xflat/Make.defs contains definitions that characterize and make environment and many definitions that derive from these environmental definitions. It should be necessary only to modify this environmental definitions to customize the XFLAT source to work in most environments. The following table identifies the key environmental definitions provided in xflat/Make.defs:

<<Table of Contents>>
<<Index>>

As of this writing, the XFLAT shared libraries have only been implemented for the ARM7 processor. However, the underlaying logic does not depend upon any characteristics of the ARM7 (other than its lack of an MMU). As a consequence, the XFLAT shared libraries should be portable to other MMU-less target platforms.

Provisions have been made in the XFLAT architecture to simplify some future port to another target platform. Only the following areas are likely to require modification:

• Dynamic Loader. All of the ARM-specific logic used with the ld-xflat dynamic loader is contained in a separate subdirectory: xflat/ldso/xflat-ldso/arm. Similar logic would have to be generated for any new processor.
• Startup Files. The (tiny) C start-up files in xflat/libc would require modification.
• ldelflib. This tool dynamically generates the low-level shared library assembly language interface. This generation, however, is done blindly without knowledge of the underlying processor architecture. All of the processor specifics are isolated as fprintf formatting statements in xflat/tools/dyncall_skeleton.def.
• ldelf2xflt. This tool contains in-line logic to handle ARM-specific relocation types. Changes would be required to this tool to handle any new relocations types. Both ldelflib and ldelf2xflt use the GNU BFD to manage access to the target binaries. Because of this, these tools should be very robust with respect to differences in target binary formats and content.
• Other Changes? As of this writing, no port to a non-ARM processor has been performed. It is likely that such an effort would reveal other changes in addition to those listed above. However, the extent of such additional changes should be minimal.

<<Table of Contents>>
<<Index>>