Going Embedded with GoboLinux

Lucas Correia Villa Real, May 18, 2006.

So, do you want to try Gobo on a different architecture? That's cool, and that's why this documentation was created for: we want to encourage you to join in the developers' corner with interesting experiments.

More specifically, this documentation is here to guide you on porting Gobo to a new architecture, which might be focused on embedded or desktop usage. The steps, examples and tools shown on this document have reached a stable branch, being used in projects such as the Brazilian's Digital TV research, where a Gobo port to the SuperH has been done, as well as the Gobo ARM port.

The remaining sections are going to focus on 2 ways of porting Gobo to a new system: by cross-compiling and by using an existing distribution as a basis to compile packages using the Gobo hierarchy.

Doing that by Cross-Compiling

While we try to make porting as easy as possible, doing this kind of task always needs some background on the subject. Cross compiling a whole set of packages and preparing the root filesystem requires that you have an understanding of the boot process, of the manual installation of a kernel image, shell scripts and many more. Reading other chapters of the GoboLinux Documentation Project might help you to acquire some of that knowledge.

Finished with the introduction, let's make a list of what you'll need. Firstly, this tutorial assumes that you have a host computer running Gobo. The Gobo team has developed numerous tools to help on the automation of the system, such as compiling programs based on simple description files, detecting the latest versions of a given application, enjauling the compile process so that the host system doesn't interfere in the compilation environment, and so on.

For this reason, the tools developed to aid on the port are based on Gobo's own infrastructure. After all, since you're porting Gobo to a new architecture we would expect at least that you're also running it on your host computer, right?

Secondly, you'll need a working cross-compiler. Since we're going to create a distribution from scratch to a different architecture than the one running on the host system, that's the way we will generate programs to it. There are many cross-compilers ready for usage out there, and some scripts that might help you to prepare your own. The following projects and cross-compilers have been tested and are recommended:

• Crosstool: Consists in a set of scripts and patches to generate a toolchain for many architectures, such as Alpha, ARM, i686, IA64, MIPS, PowerPC, PowerPC64, SH4, Sparc, Sparc64, s390 and x86_64. The current toolchains used by Gobo developers were generated by this tool;

• CodeSourcery: This is the major source for ARM toolchains, and is one of the leading companies developing the ARM EABI. If you want to get a tested and ready-to-use cross compiler for ARM, this is the place to get one;

• uClibc toolchain: If you're looking for a very small distribution it's probably better to look at this alternative. The uClibc is a tiny libc implementation which targets devices with small storage capabilities. Please note, however, that this might come with small performance penalty on some applications.

Finally, you'll need to write cross-compiler rules for the Compile tool. Compile has the ability to create binaries to different platforms, so there's a need to write a configuration file for the one you're going to use, respecting the naming convention Cross-<ARCH>.conf, where ARCH will represent the target architecture. Cross configuration files are stored at /System/Settings/Compile.

The Compile tool ships 2 sample files for the ARM and SH4 architectures. Let's give a look into the variables exported by them, taking the ARM rule as reference:

• cross_kernel_dir: specifies the path on which the kernel sources for this platform are found. Since it's very usual to maintain the kernel for the working platform on a special directory during development stage, you can do that and just specify its location here;

• cross_kernel_version: for the same kernel, specifies its release, based on the VERSION, PATCHLEVEL, SUBLEVEL and EXTRAVERSION variables exported in the Makefile;

• cross_kernel_arch: when cross compiling the kernel, one must call "make menuconfig ARCH=kernel_arch_name". Specify your architecture's name under the kernel tree here;

• cross_prefix_dir: where in the host's filesystem the new filesystem tree will be stored;

• cross_toolchain_dir: where in the host's filesystem the toolchain is installed;

• cross_sys_incdir: path to ``stdio.h'' inside the toolchain's dir;

• cross_gcc_incdir: path to ``stdarg.h'' inside the toolchain's dir;

• cross_cpp_incdir: C++ include dirs (is an array) in the toolchain's dir;

• cross_gcc_libdir: path to ``libgcc.*'' files in the toolchain's dir;

• cross_libc_libdir: path to ``libc.*'' files in the toolchain's dir;

• cross_uname_m: output for ``uname -m'' on the target machine;

• cross_configure_host: parameter to the configure script when building applications based on autoconf (-host=target_ machine_string). This string describes the CPU on which the binary generated will run on;

• cross_configure_build: parameter to the configure script when building applications based on autoconf (-build=build_cpu_string). This string describes the CPU which is doing the cross-compiling;

• cross_optimization_flags: optimization flags to be used by the cross compiler. A useful place to look for available options is the GCC info page;

• cross_compiler: prefix to the cross-compiler's executable files, such as arm-xscale-linux-gnu-gcc and arm-xscale-linux-gnu-strip.

The BootStrap tool

The process of creating a distribution from scratch involves many steps which are very error prone. Bootstrap is a tool which concentrates many scripts for these purposes, adding a menu-driven interface to make this task less focused on the details on how to generate things, but on what to install on the new filesystem.

In short, Bootstrap performs the following steps:

1. Creates a Gobo directory structure for the new port at $cross_prefix_dir, defined in the cross config file;

2. Populates its /System/Kernel/Devices dir;

3. Creates system files at its /System/Settings;

4. Installs the Scripts and Compile packages on the new tree for usage during cross compiling;

5. Installs BootScripts;

6. Prepares kernel headers to be used by Glibc cross-compilation;

7. Compiles packages selected by the user.

Given that the cross config file had been written, Bootstrap usage is pretty simple. Configuration is done by make menuconfig, where packages can be selected along with a target architecture and machine implementation. If you're porting Gobo to an architecture which is not listed by Bootstrap, you can create a new entry for it at functions/Platforms and at Config.in inside Bootstrap's root dir.

At the end of make, the filesystem generated will be available at the directory specified at the cross config file, and will be ready for usage on the target platform. Files can always be modified manually after they are generated, as they're not overwritten by subsequent make calls. The filesystem can then be shared for remote mounting over NFS at boot time, or copied to different media, depending on your interests and resources available on your platform.

Availability

BootStrap can be downloaded as a package or directly from the CVS. The current stable release is 1.0, and it can be downloaded here. CVS snapshots can be obtained in the following way:

export CVS_RSH=ssh
cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/goboscripts co tools/Bootstrap

Doing that with another distribution as a basis

Not rewritten yet, please refer to the quick and dirty gobolinux porting guide for now.