Technical Bulletin #12

Getting started with uClinux

By David McCullough

David McCullough With linux enjoying growing success in the embedded space, more and more people are looking to experiment with embedded linux and how suitable it is for their application. Unfortunately this usually requires a large investment in time to get Linux running on a platform that resembles the target hardware for the application. More often than not this investment in time is suitable deterent to investigating the linux option any further. Even more so in deeply embedded environments where uClinux is likely to be found. This paper will look at software only options (emulators) available to run the uClinux operating system. uClinux is a version of Linux for CPUs without virtual memory or an MMU (Memory Management Unit) and is typically targeted at deeply embedded systems with very little memory or permanent storage.

Why use an Emulator to run uClinux ?

The great thing about the emulators discussed here is that they are free. This make it possible to get started with uClinux and see how it sizes up for the cost of a few downloads, allowing the user to become familiar with the tools and the environment before taking the step of recommending that the next project should use Linux. The quality and reliability of the development tools can be measured before hand which is a huge advantage in pre-project planning. There is nothing worse than finding out the development tools are not up to scratch some time after committing to a delivery date.

If possible, an emulator that closely resembles the preferred target CPU should be chosen. This gives the advantage of testing the development tools and in turn, receiving hard data on memory requirements and flash ROM requirements. In some circumstances development can begin on the emulator even before real hardware is available. A good example is the Leox Project which has done most of it's uClinux work using the TSIM emulator:

Debugging can also be a much simipler task in the virtual enviroment of an emulator. It is possible to totally control the CPU emulation allowing access to debugging information that may not be possible with real hardware. An emulator can trace memory accesses and code execution at the finest level helping to find that elusive bug in the software or operating system.

Emulators can allow the developers to experiment with different performance options and their effect on usability. Something that may be useful when determining performance requirements of the target hardware. Emulators can also help to determine flash and memory requirements. All of this can be useful information early in the development process.

Criteria for choosing an emulator

When choosing an emulator there are a number of things to consider. Firstly, a good emulator choice should closely emulate the target CPU that may be under consideration, and if possible, be developed using the same tools. This will greatly increase the relevance of any work done in the emulator.

The closer an emulator is to the target hardware the better. This means emulating serial ports, timers and other devices found on the target hardware.

Debugging options should be considered. While learning a new operating system a full source level debugger can be an important part of understanding the system startup sequence. Any knowledge gained here will easily transferr to debugging skills on real hardware when it becomes available. Where a full source debug option is not available, instruction/address tracing can be useful and can normaly be added to the emulator if nothing else is available.

One of the biggst shortfalls of the emulators available to run uClinux is the absence of real network device emulation. Although it is possible to run networking on emulated serial ports using PPP or SLIP, it would be much more interesting to have an emulated network device. Emulation of commonly used embedded network devices would be particularly interesting and only requires someone to take the time to implement.

What choices are there

A search on the net for an emulator will reveal a huge list of possibilities. Only two of the endless possibilities will be discussed in some detail here. These emulators are already well supported by uClinux and offer a good coverage for embedded options CPU targets. A more comprehensive list will be provided later.

This first emulator, indeed the emulator that helped to create the first uClinux versions is Xcopilot. Xcopilot is a PalmPilot emulator that runs under Unix/X11. It offers emulation of the timer, serial ports, touch pad and LCD display along with Motorola 68000 emulation (m68k).

The second emulator is the ARMulator which is part of the GNU debugger, gdb. Currently the ARMulator offers a serial console along with many possible ARM emulations including big endian, little endian and thumb emulations.

Getting Xcopilot

Xcopilot can be obtained from many places. The most up to date source for using Xcopilot with uClinux is the version in CVS on

	cvs login

Just press enter at the password prompt, and then run:

	cvs checkout xcopilot

Otherise a reasonably recent version can be downloaded from:

Compiling Xcopilot is straight forward:

	make install

Providing all the correct libraries are in place, the result will be an Xcopilot that is ready to use.

A copy of the m68k-elf-tools will be required to build uClinux kernels and binaries for Xcopilot. These can be obtained from:

Follow the instructions for installing the pre-compiled binaries, or for the keen, build the tools from the source provided.

Getting the GDB/ARMulator

The GDB/ARMulator for use with uClinux is available from:

This page contains all the information needed to build gdb for use with the ARMulator and uClinux. There is even a selection of pre-compiled uClinux binaries that can be run in the ARMulator once it is built and installed.

A copy of the arm-elf-tools will be required to build uClinux kernels and binaries for the GDB/ARMulator. These can be obtained from:

Again, follow the instructions for installing the pre-compiled binaries, or build them from the source provided.

Getting/Building the uClinux Source

The easiest way to get started with the uClinux source is to grab the full uClinux distribution sources from:

This is a rather large file that provides both 2.0.39 and 2.4.17 kernels along with a good selection of applications, most of which have been ported to uClinux. It also provides pre-canned configurations for both Xcopilot and the GDB/ARMulator that can be selected from the config menu.

The mechanism for building for either target is essentially the same, only the target selection is different.

First extract the uClinux-dist tarball:

	gunzip < uClinux-dist-20020701.tar.gz | tar xzf  -
	cd uClinux-dist
	make xconfig

Select 'Target Platform Selection', choose a target. 3com/Xcopilot for the Xcopilot target or GDB/ARMulator for the ARMulator. Select the desired kernel version and use uC-libc as the 'C' library. Save and Exit. Here is an example of of an xconfig for Xcopilot:


One the config has finished setting up the source tree:

	make dep

When this completes, the freshly built binary images will be ready to be run in the chosen emulator.

Running uClinux in Xcopilot

There is a little bit of setup required to run uClinux in Xcopilot. From the base directory of the uClinux-dist source tree do the following.

	mkdir ~/.xcopilot
	ln -s `pwd`/images/pilot.rom ~/.xcopilot

Xcopilot is now ready to go. Just type "xcopilot" and it should be up and running uClinux in the xcopilot emulator. Here is a screen shot of what is expected.


Commands can be entered on the serial console that runs in the terminal window. Have a look around the filesystem, /dev, /bin and /etc. It will look like a very cut down version of Linux/Unix.

Xcopilot has several debug options. The simplest is the default debugger that is built in. Connect to the debugger with:

	telnet localhost 2000

From here type help to see the available debugger commands. The options available include stopping/starting the CPU and trace execution to a file. The instruction tracing is condensed in that it only traces unusual program counter changes like jumps, branches and subroutine calls.

Running uClinux in the GDB/ARMulator

From the base directory of the uClinux-dist source tree do the following.

	ln -s images/romfs.img boot.rom

Now run arm-elf-gdb on the appropriate kernel, here is an example session:

	arm-elf-gdb -n linux-2.*.x/linux
	GNU gdb 5.0
	Copyright 2000 Free Software Foundation, Inc.
	GDB is free software, covered by the GNU General Public License, and you are
	welcome to change it and/or distribute copies of it under certain conditions.
	Type "show copying" to see the conditions.
	There is absolutely no warranty for GDB.  Type "show warranty" for details.
	This GDB was configured as "--host=i686-pc-linux-gnu --target=arm-elf"...
	(gdb) target sim
	Loaded ROM boot.rom
	Loaded ROM boot.rom
	Loaded ROM boot.rom
	Loaded ROM boot.rom
	Connected to the simulator.
	(gdb) load
	Loading section .text, size 0x77b84 vma 0x2000000
	Loading section .rodata, size 0x8ddb vma 0x2077b84
	Loading section .data, size 0x8fc8 vma 0x2080a60
	Start address 0x2000000
	Transfer rate: 4507960 bits in <1 sec.
	(gdb) run

uClinux will now boot through to a shell prompt. At any point break into the debugger with ^C, set break points and examine memory and variables. Break points may be set before typing "run" to catch the early startup of the kernel. To step through the early kernel boot sequence set a breakpoint at start_kernel. For example:

	(gdb) break start_kernel
	(gdb) run


While an emulator will never replace real hardware, it can play an important role in development. It can be useful for training and experimentation and can also help with developing/debugging new operating system features.

The emulators mentioned here serve to give the user a strong understanding of uClinux and its application. Not only can they be used as a learning aide but they can also provide a practical foundation for building real devices.

An emulator can play an important part of a developers toolset and can be called on whenever it fill an immediate need.

Other Emulators

There are quite a few other emulators that can run uClinux to varying degrees.

LEON Sparc Emulator (TSIM)
Reasonable support included in the uClinux-dist sources.

NEC v850e
Quite good support with a selection of emulators available. The gdb based simulator is the easiest to use and is also supported in the uClinux-dist sources.

Coldfire Emulator
Capable of running the Arnewsh/5206 image from the uClinux-dist.

SWARM (Software ARM)
Basic support for this emulator is included in the uClinux-dist.