Electronic 'Guide to ARMLinux for Developers' - the book online
IndexPreface
Welcome!
We hope you find this book useful. If you have bought it along with another Aleph One Product such as the LART development kit, or Aleph ARMLinux, then please take the time to read it so that you know what you have, where to start, how to install, and where to turn if you have problems.
Credits
ARMLinux for Developers would not have been possible without the work of many people. We would therefore like to particularly thank:
Jan-Derk Bakker, Eric Mouw, Marc Joosen and Johan Pouwelse of the LART project for LART, blob, help and vision;
Remote 12 Systems of London for LART part sourcing;
Chris Rutter for the GNU Toolchain chapter, the Debian Autobuilder and the http://www.armlinux.org/ facilities;
Brian Bray for the ARM Structured Alignment FAQ;
John G Dorsey for his description of installing ARMLinux on an Intel Assabet;
Russell King for the orginal ARM kernel port, continuing maintainance, and the http://www.arm.linux.org.uk/;
Stephen Harris, George Wright and Nathan Catlow for their Psion documentation;
Phil Blundell for work on and advice about the ARM Toolchain, and work on Debian and Bootfloppies;
Nicolas Pitre for his work on the kernel,and the JFlash utility;
Steve Wiseman for his work on JTAG;
Holly Gates for the JTAG dongle design;
and of course the many others who have worked on Debian ARM, the ARM kernel port and the people whose expertise we have tried to incorporate into this book.
We also acknowledge all Trademarks used in this book.
Outline of the Book
Although it is possible to read this book from begining to end, most users will want to just read the most relevant sections. Everyone should read the introduction and Chapter 2. If you have bought it for use with a particular item of hardware then next read the chapter for that hardware - you will be referred to other parts of the text for more detail should you need it. Those who are not familiar with desktop Linux should read Chapter 9 to get a feel for how to use it, before trying to install anything. Developers working with a new device or with a general interest will find the chapters on tools and techniques most useful.Buying the Book
Although this guide is available in HTML and PDF formats to all users who buy the Aleph ARMLinux CDs, a printed version of the Guide can also be bought separately from Aleph One Limited.
Interested users should go to http://www.aleph1.co.uk/armlinux/thebook.html or <info@aleph1.co.uk> for further details.
Dedication
Chris Rutter was killed by a car whilst crossing the road during the preparation of this book. His enthusiasm was instrumental in my starting this project so it seems approriate to dedicate this book to him.Chapter 1. Introduction
This book tries to cover a range of hardware and aspects of ARMLinux. It assumes that you are at least a competent computer user, more likely an experienced developer, but perhaps not very familiar with GNU/Linux or the ARM and its development platforms.
There are many things that are specific to different items of hardware, and many things that are common across various devices. We have tried to avoid too much repetition, but we have also tried to make the text reasonably linear in the hardware chapters. This is inevitably a compromise. In general you should find that reading through the relevant hardware chapter will get you going, but will not go into much depth about why you are doing things and what other options there might be at each stage. We refer to other chapters that have more details on each aspect (using JFlash, patching the kernel, etc) throughout these texts. If you have feedback on the book we'd be very happy to have it, so as to improve future versions - see Chapter 13.
In a fast-moving field like this, this book will always be a work-in-progress. We give the current state of the art at the time of writing, but recognise that this will soon change. Thus we try to provide links to the places online where you can get the latest info. When you find things that are out of date, of just plain wrong, please tell us.
There will be future editions covering more devices and more subject areas. Things that will definately be in the next release are coverage of porting the kernel to a new ARM device, more information for developers using a Windows host PC rather than a Linux one, and more on debugging and simulation techniques.
The Aleph ARMLinux CD
If you have bought this book as part of our Aleph ARMLinux distribution then be aware that this follows the hallowed GNU/Linux principle of releasing early and often. The distribution is not yet finely tuned to the needs of various embedded devices. It has parts that are specific to small ARM devices, and parts which are generic, but assume a desktop environment. The specific part contains this document, kernels, utiltites and RAMdisks suitable for the devices covered in the book, pre-compiled x86/ARM toolchains, and current kernel source and ARM patches. The generic part form the bulk of the distribution and is essentially the standard Debian ARM distribution, containing a huge array of packages and all the corresponding sources. These are very useful, providing an enormous library of things that you can run on your ARM hardware, but the Debian installer is not yet set up to install to embedded systems. You need to make your own RAMdisks from the parts available to use these binaries. There are several projects underway to make this process easier, including CML2+OS from http://www.emdebian.org/ which is included. Future releases will have significant improvements in this area.
Have fun!
Nomenclature
Throughout this book we distinguish between the Linux kernel and the GNU/Linux operating system. Many people call both of these things Linux, but this is somewhat misleading and certainly unfair to the GNU project which has created almost all of the basic operating system software (shells, compilers, editors, tools, documentation systems, document processors etc.) It had done all this before the Linux kernel came on the scene and enabled the powerful combination we see today of GNU software running on the Linux kernel. We feel the distinction is important as well as reducing confusion and thus maintain it in this document.Chapter 2. Embedded ARMLinux: Fundamentals
Introduction
The fundamental requirement for a GNU/Linux system is a kernel and a filing system for it to execute things from.
The kernel is an autonomous piece of code that doesn't need any other files or libraries to get started, although without a root filing system it will simply stop after initialising the system as it no files to operate on.
The filing system can be loaded from a range of different hardware devices (hard disk, RAM, ROM, CD and NFS mount) and must be in a format that the kernel understands. For embedded systems it is often a RAMdisk. The kernel and RAMdisk both need to be loaded to correct places in memory and the kernel executed. This can be done in various ways, typically by loading over a serial connection or from local flash RAM.
In order to be able to load anything from anywhere some kind of bootloader must be present on the target hardware which knows how to load files and execute them. This can be installed in a physical fashion by inserting a pre-programmed ROM/EEPROM or flash chip, but is more usually installed using a JTAG port, which allows instructions to be executed from an external input, and thus an initial program loaded.
As there are so many possible boot scenarios we cannot describe them all in detail. We will describe only the most common (which are the most useful for typical situations) but also make the principles clear so you can do something more exotic if you need to.
Bootloaders
Bootloaders are highly system-specific. Some ARM platforms share the same loaders, but on the whole you get a different one on every system. This can be a boot ROM like the NeTTrom in a Netwinder, or it can be the native OS like RISCOS in a RiscPC, or EPOC in a Psion5, or it can be a dedicated bootloader installed into Flash, like Angel or Blob in the LART and Assabet. If you are porting to a new ARM platform then you will need your own bootloader. You may well be able to base this on one of the existing GPLed ones, or you may already have something that can be modified to load ARMLinux instead of whatever the device used before.
When talking about bootloaders it is important to remember that if the target is not autonomous then the loader has two parts:
One part on the target to receive the kernel and RAMdisk; and
another on the host to send it.
There are two bootloaders commonly used with the LART and Assabet: Blob and Angel. Angel is part of ARM's Development toolkit, and can also be used as a debugger, but we use it with a companion program Angelboot instead. Angel is a simple loader that receives a kernel and RAMdisk over the serial port and loads them to specified addresses before running the kernel. Blob is a more complex program that can do the same as Angel but can also install a kernel and RAMdisk permanently in flash RAM so that the target can subsequently boot autonomously.
See Chapter 6 for details of configuring and using these programs. Brief typical use is covered in the install section for the relevant target device.
JTAG
Getting the target side of the bootloader installed is normally done with the Jflash utility (both Windows and Linux versions exist). This drives the JTAG interface through the printer port of the host PC. The Linux version is called JFlash-linux. Note that this program is different for each target as it depends on knowing the exact hardware of the target, so JFlash-linux for Assabet and JFlash-linux for LART are different and you need to use the right one.
Table of devices and tools
| Device | JTAG | Boot loader(s) |
|---|---|---|
| LART | Jflash,Jflash-linux | Blob |
| Assabet | Jflash,JFlash-linux | Angel, blob |
| Psion5 | - | Arlo |
Host machine
If the target has sufficient IO devices (eg screen and keyboard) then it can be used without a host. However, during initial development a host is normally used as a console (screen and keyboard), for compiling new code and for monitoring debug output.
There are several reasons why this is practical:
you will probably keep rebooting the target;
it will probably crash a lot if you are doing any low-level development, or the hardware's not quite debugged yet;
there may well not be space for the toolchain software on the target;
you will normally be more familiar with the host environment.
As the host is usually an x86 PC rather than another ARM-based machine this means that you will need to cross-compile software to run on the target processor. You can arrange to use an ARM machine as the host (eg an Acorn Risc PC, Netwinder, CATS board) but even here you usually need to separate the host and target environments as they will probably be using different kernel versions and perhaps library versions.
You can have either a GNU/Linux or a Windows box as the host. As you are working with Linux on the target it is useful in many ways to also have a Linux host - the toolchain is easier to set up, you can easily mount and try out your RAMdisks etc. Much of this book assumes that you have access to a GNU/Linux host. However we recognise that many developers wil have a Windows box on their desks and may not wish or be able to change just yet. The best solution is to the use the Cygnus unix-like environment for Windows which gives you the functionality you need. A chapter for this book, describing the necessary software and techniques, is in preparation for the next edition. In the meantime either use your skill and judgement, or get a GNU/Linux box too.
Getting a cross-compiler toolchain set up used to be very difficult, requiring much gurudom and attention to a host of details but with the precompiled toolchains on this CD it is very easy. Chapter 8 gives details of both the ready built toolchains you can install, and explains how to build a new one should you need something different from that which is provided.
RAMdisks
The RAMdisk is a very useful kernel facility that lets you load the files you need on the system into RAM along with the kernel. It take the form of a compressed filesystem. The kernel automatically allocates RAM for it and uncompresses it, then mounts it as the root filing system.
Again, there are many variations possible on this theme, but the conventional setup is to format the RAMdisk as ext2, the normal Linux disk filesystem. For this to work you need to specify the correct kernel options: RAMdisk support (CONFIG_BLK_DEV_RAM, CONFIG_BLK_DEV_RAM_SIZE, CONFIG_BLK_DEV_INITRD) and support for the filesystem used (normally ext2 - CONFIG_EXT2_FS).
There are suitable example RAMdisks provided for the devices covered in this manual on the CD. There are also several available on-line, where developers have made their own available for others to use. We recommend that you use one of these to get started, however for many applications you will need to make your own. It's not difficult, and the process is described in the section called Making a RAMdisk in Chapter 7.
Chapter 3. LART
This chapter introduces the reader to the Linux Advanced Radio Terminal (LART) by describing hardware specifications and a range of relevant resources.
Background
The LART is part of a project at the Technical University of Delft to do wearable computer research. The first aspect of this was building a suitable platform as nothing with the right combination of low-power, high-performance and low cost existed at the time. The result is offically the 'Linux Advanced Radio Terminal' but a look at the Canonical Abbreviation/Acronym List suggests this may be a contrived acronym.
Part of the design philosophy was that it could be built without expensive facilities and it was easy to add bits of hardware for your own purposes. This combined with its power/performance ratio makes it an excellent development tool. In practice buying the parts to make them yourself is a time-consuming and difficult process, so Aleph One and Remote12 Systems have made it available as an assembled tested development kit. We hope this document will get you going in LART/ARMLinux development quickly and reasonably painlessly.
Hardware
Aleph One LART development kit
Many users of this chapter will have bought the Aleph One LART development kit. If you haven't, the information here will still be useful but references to the supplied connectors and cables will need to be adjusted to whatever equipment you are using. The Aleph One kit comprises:
LART main board with blob bootloader installed;
This Guide to ARMLinux for Developers book on paper and CD ROM;
Aleph ARMLinux distribution for LART including suitable kernels, RAMdisks and tools for the LART, as well as all the Debian 2.2release2 packages in binary and source form on 5 CDs;
JTAG adaptor board;
Parallel extension cable;
Twin-headed serial cable;
Power cable.
This is everything you need to get going (apart from a host machine); we hope you enjoy developing on it.
(We no longer sell LART kits, but you may be interested in our Balloon Board Development Kit.)
Mainboard
The specifications for the LART mainboard are as follows:
220 MHz Digital SA-1100 StrongARM CPU;
32 MB EDO RAM;
4 MB Intel Fast boot block Flash memory;
power usage of less than 1W;
performance in excess of 200 MIPS.
The board can run standalone, booting an OS from Flash.
The 4MB Flash is sufficient for a:
bootloader;
compressed kernel;
compressed RAMdisk.
The LART accepts an input voltage of between 3.5 and 10 Volts, although it can be modified to accept up to 16V. The on-board DC-DC converters have an efficiency of between 90 and 95%.
Connectors
Signal
Almost all signals from the SA-1100 are available on the external connectors.
The High-speed Connector is an SMD with 0.8mm pitch and offers:
access to the 32-bit data bus;
access to all 26 address lines;
high-speed peripherals with a data rate in excess of 400 MB/second.
The Low-speed Connector is actually three separate through-hole connectors with a 2mm pitch which:
export General Purpose (GP) I/O pins and most of the data/address buses to implement ISA or PCMCIA-based peripherals;
are ideal for connecting to low-speed devices.
Other
Additional connectors include a:
reset connector;
voltage/current measurement point;
power connector;
JTAG connector.
Kitchen Sink Board
The Kitchen Sink Board (KSB) provides the LART with a:
stereo 16-bit 44k1 audio output at line and headphone levels;
44-pin 2mm IDE/ATA interface;
connector for a single or quad Ethernet board;
two PS/2 connectors for keyboard and mouse;
mono audio I/O from an UCB1200;
connectors for POTS, IrDA, USB clients, video and touchscreens.
Ethernet Boards
The Ethernet is a 10Base-T adaptor that connects through the Kitchen Sink Board.
The core of the board is a Crystal CS8900A Ethernet chip with :
facilities for a bootROM;
an 8-bit parallel output port.
Installing for the LART
Power and Serial Connections
Refer to the diagram and picture to familiarise yourself with the device. The view showing the StrongARM CPU and large inductors is the 'top' of the board throughout this document.
Power is supplied to the four pin connector in the top right. The supplied power lead is wired such that it doesn't matter which way round you plug it in - polarity will be correct. (The two central pins are +ve, the two outer -ve). The red LED next to the crystals in the lower left hand corner should glow when power is applied. At 5V, initial start-up current for a lone LART is ~160mA, dropping to ~80mA after a few seconds. Note that the supply voltage is between 4V and 10V. Some documents (including the LART website at the time of writing) give an upper limit of 16V but this will damage your LART! The LT1266 can take 20V nominal, but the design uses voltage doubling so the input voltage must remain below 10V unless the PSU is changed around (which can be quite easily done)
The serial connection is the 2x3 header. This supplies two simple serial ports (ground, data out, data in). The supplied cable should be plugged in so that the lip on the blue 2x3 connector points downwards. The white 9-pin-D connector is serial port 1; the blue 9-pin-D connector is serial port 2. Plug the white connector into your host computer.
If you need to re-flash the blob loader then you need to attach the JTAG dongle to the 1x8 header. The JTAG board should be attached so that the components on it are on top - i.e. components are on the same side as the StrongARM CPU on the LART.
Using JTAG and JFlash-linux
It is possible to program flash memory through the SA-1100 JTAG interface. A utility to do this is provided. Aleph One supplied LARTs will already have had this done so you can skip to the next section.
In order to use the JTAG programmer, take the following steps:
connect the parallel cable to your computer's printer port;
connect the JTAG dongle to the cable;
connect the other end of the JTAG dongle to the LART, with the JTAG component side the same way up as the LART main board;
turn the LART on.
You can then issue the following command as root:
./Jflash-linux blob-1.0.7b
and you should see something like the following after which the LART will reset itself before running blob.
using printer port at 378 |
LART JTAG reset problem
Output like this is typical of the 'JTAG reset problem':
error, failed to read device ID |
This is solved by putting a 100 OHM resistor between pins 6 (+3.3V) and 7 (nTRST) on the JTAG connector. nTRST will thereby be pulled to +3.3V so the JTAG bus won't be able to reset itself. This modification is already done on Aleph One supplied JTAG boards as they don't work without it. You can make other modifications to have the same effect (eg connect the JTAG reset pin to the MAX811 reset chip on the LART).
Serial Monitor
The only means of communicating with a bare LART is via its serial port. You should run a suitable piece of terminal software on your host. For a GNU/Linux host we recommend Minicom, which is very capable and easy to use.
Configuring Minicom
In order to configure Minicom, take the following steps:
Run it with minicom -o to get to setup.
Set it to VT102, serial port ttyS0 (or ttyS1 if you are using that port) 9600baud 8N1 (8 data bits, No parity, 1 stop bit), no modem init string, no hardware handshaking.
Save that as lart config. Running Minicom as minicom lart will run it up with these options.
If you don't use Minicom for anything else then you can make these settings the overall default - Minicom calls it dfl - settings.
If you aren't sure which serial port you are using for the device, but your mouse or modem is in the other one then look at these thing to determine where the mouse or modem are plugged in:
/etc/gpm.conf will show what device gpm is using as your mouse
ls -l /dev/mouse is normally a link to the serial port your mouse is plugged into if you have a serial mouse
ls -l /dev/modem will give the same info for your modem.
If you don't have anything in either port then just try both with the following boot proceedure.
Starting up
OK, now we're ready to go.
The reset pins are at the bottom left of the board, and a jumper is supplied to do a reset. The board will remain in reset as long as the two pins are connected. You may wish to attach a switch to these pins if you are resetting a lot!
On reset you should then see (from within your serial monitor) something like:
Consider yourself LARTed! |
Note: It always says Loading kernel/ramdisk whether or not a kernel and RAMdisk are actually present. It will just hang if it tries to boot a 'blank' kernel.
Blob version 1.0.8-pre2, |
Now press Enter within 10 seconds, otherwise it will go on to try and boot a kernel it doesn't yet have and will just hang. This should get you a blob prompt:
Autoboot aborted |
Getting a kernel and RAMdisk
There are several pre-compiled kernels available on the CD and on-line. When you want to compile your own refer to the section called Compiling a Kernel in Chapter 7. The correct default config setting for LART is: make lart_config.
Uploading a kernel and RAMdisk
In order to upload kernels via the serial port to blob you need to put them in the correct format. Blob expects uucoded files. uuencode's syntax is:
uuencode {input filename} {name in uucoded file}>
output filename
so you uucode a kernel called zImage-2.4.1-rmk1-np2 like this:
uuencode zImage-2.4.1-rmk1-np2 zImage > zImage-2.4.1-rmk1-np2.uu
At the blob prompt enter 'download kernel' to upload a kernel. Blob will respond with:
Switching to 115200 baud |
Switch to 115200 like it tells you (otherwise the upload would take hours). If using Minicom this is done by ALT-O, select 'Serial port setup', then E for 'Bps/Par/Bits', I for '115200'. Then Enter,Enter,Escape to get back to the prompt.
You ought to be able to use Minicom's 'ASCII upload' at this stage, but it doesn't seem to work reliably with no flow control, so we recommend you use a second virtual terminal and do:
cat zImage-2.4.1-rmk1-np2.uu > /dev/ttyS0
which simply copies the uucoded kernel to your serial port. Switch back the Minicom virtual termainl and you should see a line of dots printed as the kernel loads.Once the upload is complete blob will print something like:
(Please switch your terminal back to 9600 baud) |
Switch your terminal back as directed and hit return to get a blob prompt. You can check the size of the uploaded kernel by typing 'status'.
Now you need to do the same proceedure again to upload a RAMdisk. The only difference is that the blob command is 'download ramdisk' instead, and obviously you use the filename for the (uucoded) RAMdisk.
Blob has the facility to save uploaded kernels and RAMdisks into its flash RAM. However at the time of writing it is not capable of writing to the flash it is itself running from so this function only works if you have a separate bit of flash memory containing blob to plug in. It needs modifying to be able to copy itself to SRAM first and then execute from there.
Which kernel/RAMdisk to use?
There are several kernels and RAMdisks supplied on the CD, and these will be updated along with the releases. We have found that a good set of software to use at the time of writing is: blob v1.0.7b, zImage-2.4.0-rmk5-np2, and either ramdisk-lart-glibc-2.1.2.gz (for a basic RAMdisk), or ramdisk-2.4.0-rmk5-np2.gz for a bigger one including an mp3 file (which needs a KSB to play).
Booting the kernel
So finally we are ready to go. At the blob prompt enter 'boot'. It says
Starting kernel... |
Uncompressing Linux........ |
Resources
A number of useful schematics for the mainboard, kitchen sink, ethernet board and JTAG programmer are available in PDF format on the CD and from the LART website. On the CD they are all in LART/Hardware/ and only the schematics for the version of hardware in production are present. If you want to see the older schematics then you'll need to go to the website.
- LART Revision 4 mainboard schematic
CD: /hardware/LART/Lart-rev-4.pdf.
Web: Lart-rev-4.pdf.
- LART Revision 3 mainboard schematic
Mainboard
- CPLD U9 Revision 2
- CLPD U1 Revision 2
- Kitchen Sink Board Revision 2
Kitchen Sink Board (KSB)
- Ethernet Card, four channel, revision 1
- Ethernet Card, single channel, revision 1
Ethernet Board
- JTAG dongle schematics
- JTAG dongle Bill-of-materials
- JTAG dongle hardware distribution with gerber files
- Jflash
JTAG
Chapter 4. Installing ARMLinux on the Assabet
This chapter describes how to get your Assabet running ARMLinux.
Assabet: Background
The Assabet is an SA-1110 evaluation board which may be repackaged as a PDA. Notable features include:
The availability of programming utilities like the JTAG Programming Software V0.3 (for Windows) and Jflash-Linux (for Linux), and the bootloader Angelboot.
Neponset - a SA-1111 Development module with many additional interfaces.
Use of the 2.4 kernel series with support for the Assabet and Neponset via a patch chain.
The capacity to run MicroWindows although a backlight power source needs to be added on 'build phase 4' or earlier boards.
There is also support for Compact Flash on the Assabet and on PCMCIA support for the Neponset. In addition, the Socket LP-E CF + Card is now operative as is the IBM Microdrive.
Hardware Setup
Note: The behaviour of the hardware, bootloader and kernel can vary because of the presence of Neponset - the Microprocessor Development Module. Readers who intend to use Neponset with Assabet should therefore refer to the section called Install Neponset.
Preparing the Board
Carefully remove the Li-ion battery and LCD/touchscreen by releasing the fasteners on the board receptacles.
Install Angel
On Assabet (and Neponset), the bootloader can be installed by physically inserting the pre-programmed flash chips supplied with the kit.
Determine whether the board has a WindowsCE bootloader pre-installed by opening the StrataFlash sockets and examining the labels on each memory component. For precise details of the process of manipulating memories, refer to The Intel StrongARM SA-1110 Microprocessor Development Board Users' Guide section 2.3. (See the section called Useful Resources for the appropriate URL).
Remove all power from the board and remove the jumper from the master power clip if it is installed (this disconnects the battery power). Open Socket E11 (StrataFlash) by sliding the middle panel away from the notch before lifting the doors. Socket E12 can also be opened in a similar way. (E12 is directly opposite to E11 on the other side of the board).
The WindowsCE parts have a label which is similar to "WinCE E-Boot V3.0 L". Remove these parts with the suction part selector (similar to a pen supplied within a tube) and replace them with the parts which are labelled "Angel DB1110B 207D L".
Power and Serial Connections
Power, JTAG, RS232 and POTS connections are made through base station - a 14-pin header. Connect the serial cable to your development workstation which - on a SA-1110 - means that the header should be attached to serial port 1.
LED D4 should light up when the power is applied. Angel will then activate LED D8. After interrupt initialisation, Angel will strobe LED D9 four times. Supplementary information on the reset sequence can be obtained from DB1110_diag.txt which is bundled with Angel (http://developer.intel.com/design/strong/swsup/SA1110AngelKit.htm).
Install Neponset
It is possible to attach the SA-1111 Development Module by using either of the 140-pin connectors which are found on the Assabet.
Make a record of the switchpack SW2 settings because these affect selection, bus speed and other important parameters. A comprehensive explanation of switch meanings can be found in the readme.txt which is included in the Angel distribution although a summary of switch meanings is provided in the following table.
Table 4-1. Switch Options for Switchpack SW2
| switch | off | on |
|---|---|---|
| SW2-1 | reserved | reserved |
| SW2-2 | reserved | reserved |
| SW2-3 | debug port is UART3 | debug port is UART1b (on Neponset) |
| SW2-4 | bus speed is 103MHz | bus speed is 51MHz (clamped to 51MHz if PLL==147MHz) |
| SW2-5 | flash device page mode enabled | flash device page mode disabled |
| SW2-6 | Angel fast boot mode | Angel debug mode (see DB1110_diag.txt) |
| SW2-7 | PLL==206MHz | PLL==147MHz |
| SW2-8 | boot from flash on Neponset | boot from flash on Assabet |
Note: All switches can be left in the off position except for the SW2-8 which can be left on.
Fixing Neponset
Some copies of Neponset may contain a bug involving the on-board Philips UDA1341 audio codec. The bug involves the L3 MODE signal coming from the SA-1111 which is available from PWM1 - the dual-function pin. Phase 4 Neponset boards incorrectly route this signal to PWMO which prevents any configuration of the codec from software. However, this problem may be solved by unsoldering the jumper wire at J7 and moving it immediately adjacent to J4.
Getting a Cross Compiler
We recommend that you install the emdebian cross-development environment supplied. See the section called Emdebian in Chapter 8.
Getting a kernel
There are several pre-compiled kernels available on the CD and on-line. When you want to compile your own refer to the section called Compiling a Kernel in Chapter 7. The correct default config setting for Assabet is: make assabet_config, and if you are using Assabet and Neponset together than it is make neponset_config.
Uploading to the Assabet
Power it up and connect to the serial port.
Get the Angelboot code. The precompiled version should work but you will need to be root.
Copy dot.angelrc and angelboot from Assabet/tools/angelboot on the CD your development directory and rename dot.angelrc to .angelrc. Then .angelrc becomes classified as a hidden file so your filer may hide it from you. You will however, need to edit .angelrc so that it has the following settings:
base 0xc0008000 |
Note: You should change device /dev/ttyS1 if your cable is plugged into ttyS0.
Configuring Minicom
In order to configure Minicom, take the following steps:
Run it with minicom -o to get to setup.
Set it to VT102, serial port ttyS1 (matching the .angelrc file) 9600baud 8N1 (8 data bits, no parity, 1 stop bit), no modem init string, no hardware handshaking.
Save that as assabet config. Running Minicom as minicom assabet will run it up with these options.
If you don't use Minicom for anything else then you can make these settings the overall default - Minicom calls it dfl - settings.
OK. Now we are ready to go. Make sure the Assabet is powered, reset, that you have the 4 flashes on the orange LED and that the serial port is connected. Run:
./angelboot
This will read the config from .angelrc before uploading the kernel and RAMdisk images. You should see the upload indicated, followed by several lines of stars during the kernel upload, then dots during the RAMdisk upload. See the section called Angel and Angelboot in Chapter 6 for more details on how angelboot is configured.
If everything works OK you should see a penguin and a login prompt on the touchscreen which will disappear after a few minutes. Hitting Return in Minicom (start it if it hasn't already with minicom assabet) should get you to a root prompt from where you can login as root. You will not need a password.
daa-daa!
Re-flashing your Assabet
If your angelboot copy in strataflash becomes corrupt for any reason you can put angelboot back again by using the JTAG interface.
To use the JTAG interface, you will need:
To connect the custom 14-pin connector on the JTAG/serial/phone cable to the Assabet.
To connect the JTAG part (25-pin D connector) of the JTAG/serial/phone cable to your parallel port. Nothing else should be using the parallel port at the same time and you will need to be root as well.
To connect the power supply to the Assabet and power it up.
The Jflash-linux code (or Jflash - the Windows version). The pre-compiled binary suplied on the CD in Assabet/tools/Jflash/should work OK.
The binary of the bootloader which you will be putting in flash. Angel.bin is supplied with the Jflash distro.
To place the bootloader in flash, type:
./Jflash-linux angel.bin
When this process has finished, reset the Assabet and the LEDs should show everything is working OK.
RAMdisks
A selection of useful RAMdisks is provided on the CD in Assabet/RAMdisks. These are the files that you upload using the 'otherfiles' entry in Angelboot.
See the section called Making a RAMdisk in Chapter 7 for details of making your own.
Using the Audio Devices
Using the ramdisk_ks RAMdisk it is possible to play a sound by issuing the following command:
cp <file> /dev/dsp
Where file is 44kHz stereo WAV file. Well, you can play any file you like this way, but it'll sound horrid if it's not a WAV file.
PCMCIA Support
For PCMCIA to work you need kernel PCMCIA support compiled in and the cardmgr daemon in the RAMdisk and running. This is included on ramdisk_ks (2.5MB - expands to 6.8MB) which is on the CD. Use this RAMdisk if you want to use the CF slot on the Assabet.
To get a cf disk recognised, simply plug it in. You can then check it with the cat /proc/bus/pcmcia/00/stat command.
The disk can then be mounted in the following manner:
mount /dev/hda1 /mnt
Note: If you just pull disks out then things can get rather broken (and you may have to reset). You therefore need to umount the disk first.
The CF Network Card
You need to configure the card for your network environment in /etc/pcmcia/network.opts. You can then fill in IP and gateway details or simply use DHCP if it is available. Then, when you plug in the card, the eth0 interface is automatically created and the script is run to ifconfig the device. If you fill in an NFS mount in etc/fstab and specify the mount option in /etc/pcmcia/network.opts, the NFS mount is automatically done when you plug the card in and suddenly the network is available to you, making development and testing much easier.
Copying Things off a CF Disk
It is possible to copy things off the CF disk in a situation where they won't fit onto the RAMdisk.
You can use the rest of the RAM (if some is free) by doing:
mke2fs /dev/ram1 (creates an ext2 filing system in ram)
mkdir /mnt/ram
mount /dev/ram1 /mnt/ram (mounts the ramdisk)
This defaults to creating an 8MB RAMdisk. Now you have 8Mb of 'disk' available to copy things into which will remain until you power down. You can just copy things out of /dev/hda1/<path>/<file> to /mnt/ram/<file> up to the size of the new RAMdisk.
Useful Resources
Additional information can be obtained from:
The Intel StrongARM SA-1110 Microprocessor Development Board Users' Guide (http://developer.intel.com/design/strong/guides/278278.htm).
The Intel StrongARM SA-1110 Microprocessor Developers' Manual (http://developer.intel.com/design/strong/manuals/278278.htm).
The Institute for Complex Engineering (ICES) Technical Report (http://www.ices.edu).
Chapter 5. Installing ARMLinux on the Psion 5
This chapter describes how to install ARMLinux on your Psion 5 or Geofox One.
Introduction: Background
The Linux7k project is an effort to port the widely used Linux kernel to the Psion Series 5 and later pocket computers.
So far the team has ported the Linux 2.2.1 Kernel to the Series 5 and Geofox One and created Arlo and several initial RAMdisks (initrd) for the project. Work then stalled for a while as Psion were slow to release hardware information for later machines, but is now progressing again with the 2.4.1 kernel now booting on a Series 5mx.
Psion Series 5 Specifications
- Memory
4 or 8MBs.
- Processor
CL-PS7110 ARM Processor 18 MHz.
- Display Resolution
640x240 (Half-VGA).
- Display Type
Monochrome Touch-Screen (16 shades).
- Removable Media Type
Compact Flash™ (CF) Disks.
- Default OS
EPOC32 1.00 or 1.01.
Specs
How Does it Work?
Bootloader - The bootloader, Arlo does for EPOC what Loadlin does for DOS. It releases the memory from EPOC, places the kernel and initrd in the appropriate places in memory, and then boots the Linux kernel.
Kernel - The kernel has patches applied to it, which makes it compile for ARM based systems as well as having a few more patches for the Psion Hardware. The kernel port to the Series 5 is basically finished now.
Initrd - This is a virtual filing system image, which contains a miniature version of Linux. These can range in size but the more RAM used for the RAMdisk will leave less for the operating system. The kernel loads these images as the root partition.
Preparation
You will need:
A backup of your Psion's disks (this is very important as everything in your C: drive will be lost; your D: drive should escape, but don't count on it.
The Psion installer;
Arlo for your model of Psion (5 or 5mx);
A glued kernel image;
A compressed initrd;
A paperclip or similar, thin, blunt item (to reboot your machine).
Booting using Arlo
Copying Files onto the Psion
The easiest way to get the files onto your Psion is to use the transfer software for your host machine. This is PsiWin for Windows, Plp tools for GNU/Linux and PsiFS for RISCOS. Use this to transfer the necessary files onto the Psion's RAMdisk or CF through EPOC. For example, to copy the arlo.sis file onto the Psion's C: drive (RAMdisk) using plptools you type the following command:
rfsv write arlo.sis c:/arlo.sis
Installing Arlo
You need to install Arlo (the bootloader - equivalent to LILO) onto your Psion. To do this, extract arlo-0.51.tgz and copy the Arlo.sis file to your Psion, then copy INSTEXE.EXE and run it. This should change the icon for Arlo.sis which you can then run and it will install itself to either C: or D: as you select - it will work fine from either. You need to reinstall it each time you boot Linux. If you install it to a CF disk, you won't have to re-install each time - the section called Creating a Filesystem on your Compact Flash
Getting the Kernel
You need a kernel for this project. I would recommend trying one of Werner's precompiled ones. A good one to try is stable-221-cb23-519-psi.gz.
Next, uncompress the glued kernel image with:
gunzip <glued image name>
and copy the glued-* and initrd-*.gz files to C:\ on the Psion as image and initrd.gz.
Getting the Kernel from EPOC
Loading the Kernel
At this stage you are ready to boot into Linux. Double check you have good backups of your Psion and then double-click Arlo.exe. You will see:
Loading logical device Opening the channel Commands are: ... Option buffer at address XXX Memory description at address YYY > _
Now type:
l image
and you should see:
Opening file image Succeeded File size XXX Loading XXX bytes to address YYY Read XXX bytes No pages = ZZZ > _
Loading the initial RAMdisk (initrd)
Now type:
l initrd.gz
and you should see:
Opening file initrd.gz Succeeded File size XXX Loading XXX bytes to address YYY Read XXX bytes No pages = ZZZ > _
Passing Additional Parameters into the Kernel
If you need to pass any other parameters into the kernel at this point (for example an alternative root filesystem) you need to type:
o root=/dev/hda2
A full description of kernel parameters can be found in /usr/src/linux/Documentation/kernel-parameters.txt.
Running the Kernel
Now type:
b
Your Psion should now boot into Linux!
If it does a double bleep and then puts up the EPOC logo, something has gone wrong. Try reinstalling Arlo (from the Arlo.sis and INSTEXE.EXE files).
What can I do Now?
Good question. Start by mounting /proc, it's satisfying and actually useful.
Type:
mount -t proc /proc /proc
You can then ls /proc if you want, good, eh?
You can also mount CF disks with:
mount -t msdos /dev/hda1 /mnt
You will get some errors when you first mount the disk and long filenames will produce errors when they are ls'd.
If you are feeling brave you could:
dmesg > /mnt/dmesg.txt
But you run a greater risk of trashing your CF disk.
Creating a Filesystem on your Compact Flash
If you want to boot your system off a CF disk, you need to repartition it. You will need a reasonably sized CF though (over 16MB).
First, you boot into initrds3.gz with a kernel that supports CF disks. When this has booted up, you need to execute fdisk /dev/hda. You can then repartition your system. Ideally you should make a 4-6MB Fat16 partition as /dev/hda1, and then assigning the rest for Linux (/dev/hda2). When you have done this, boot into EPOC and format the CF. Install Arlo, a kernel and an initrd in the root of this partition. Now you don't have to re-install Arlo every time you reboot.
To boot a CF based system, you need to pass the appropriate option into the kernel (see the section called Passing Additional Parameters into the Kernel), alternatively, you will need to use the rdev command to alter the flags in your homebrew kernel before you glue it.
Autobooting Arlo from Reset
To automatically boot Arlo (or in fact any EPOC program) you must create a \system\data\wsini.ini file on your CF FAT partition; it should contain the following line:
STARTUP d:\arlo.exe
This presumes you have the Arlo executable on the D: drive (compact flash) and the associated Arlo.
How do I get Back to EPOC?
Type:
sync
sync
sync
Close the machine.
On the Psion:
Open the battery backup door and locate the small copper coloured circle near the battery, using a partly unfolded paperclip or similar, gently press in the copper coloured circle. Now close the backup battery door, and, while holding down both shift keys press the Esc/on key. The machine should bleep once and then display the Psion 5 splash screen, after a delay you will be back in the EPOC system.
On the Geofox: (info supplied by Hennie Strydom).
It is mostly identical to the Series 5, with the single exception that the reset switch is next to the speaker on the bottom of the Geofox.
Rolling your Own (Cross Compiling)
Cross Compilation Environment
You will need a cross compilation environment if you want to compile your own kernels, or if you want to compile your own applications for the system. To set it up, you will need the xdev package which is provided at http://linux-7110.sourceforge.net/. Uncompress this file in the / directory of your desktop Linux system. You then need to set your PATH to include /scratch/psion/xdev/bin. Check the xdev-0.README for full details.
Compiling a Kernel
Alternatively, you can create your own kernel, using the cross compilation environment described earlier. To compile a custom kernel, you will need to download the following files:
linux-2_2_1.tar.gz
patch-2_2_1-rmk2.gz
linux-2_2_2-philb-990208.gz
crash+burn-26_patch.gz
Assuming that you have downloaded these and copied them to $HOME/Linux7k, execute the following commands:
cd $HOME/Linux7k
gunzip linux-2_2_1.tar.gz
tar -xvf linux-2_2_1.tar
zcat patch-2_2_1-rmk2.gz | patch -p0
zcat linux-2_2_1-philb.gz | patch -p0
cd linux
zcat ../crash+burn-26_patch.gz | patch -p1
These commands have now patched the Linux kernel for use with the Psion Series 5.
You must now configure and compile the kernel. To configure it, execute:
make xconfig
Or, if you don't have X Windows, execute:
make menuconfig
When you have done this, execute this command to make the kernel:
make Image
This command will create a kernel image in arch/arm/boot/Image.
Glueing the Kernel
You must now glue the kernel, so that it can boot on the Psion. This basically adds the ARM bootstrap code onto the front of the kernel. To do this, execute the following commands:
cd ../
gunzip boot-13.tar.gz
tar -xvf boot-13.tar.gz
cd boot
make ./glue.pl ../linux/arch/arm/boot/Image > ../kernel_image
These commands will now make a glued kernel image in $HOME/Linux7k/kernel_image. You may now use this kernel image as your kernel.
Debugging
GDB Stub
There is a GDB stub available from the sourceforge ftp site written by Noel Cragg. The README details all you need to know.
Armulator
To simulate the Psion 5 on your desktop with full debugging capability you can use the http://staticip.cx/~benw/linux7k by Ben Williamson, cool bit of kit.
Resources
Web sites and Mailing Lists
The following web sites hold information about the linux-7110 project:
To be completed...
Mailing Lists
The <linux-7110-request@redhat.com> mailing list for information on how the project is progressing. To subscribe, write subscribe in the subject area of your email.
Plp Tools
This is the easiest program to transfer files from your Linux desktop to the Psion, pretty much plug-n-play.
EPOC Program Installer (Instexe.exe)
Included in the Arlo-0.51 distribution.
Chapter 6. Tools and Utilities for Booting
Blob
The Boot Loader Object (Blob) allows the user to:
initialise the hardware (CPU speed, memory, interrupts, RS232);
boot a Linux kernel and provide that kernel with a RAMdisk;
download a kernel or a RAMdisk to the target device;
write a freshly downloaded kernel or RAMdisk to the flash memory (see below for limitations).
Blob was originally written for the LART by Jan-Derk Bakker and Erik Mouw, but has also been modified to work on the Assabet by Jeff Sutherland and Chester and on the Intel Brutus SA-1100 evaluation platform by Erik Mouw, and on the PLEB Linux board by Adam Wiggins. You need to compile the correct version for the hardware you want to use it with as the hardware varies in important ways (processor, memory type and layout, debug serial port).
Using Blob
Assuming that you have already installed Blob then this is how you should use it. If you need to install the boot loader for your device read the chapter on that device or Chapter 2 for details.
connect a terminal (or a terminal emulator like miniterm or Seyon) to the target device's serial port;
use the appropriate settings for your device: usually 9600 8N1 or 115200 8N1; on the LART there is no hardware flow control so you'll need to turn that off too;
use the appropriate terminal emulation, usually VT100;
switch the target device on.
You should then see something like (this example is from a LART):
Consider yourself LARTed! |
Note that it always says Loading kernel/ramdisk whether or not a kernel and RAMdisk are actually present. It will just hang if it tries to boot a 'blank' kernel.
Blob version 1.0.8-pre2, |
If you didn't press Enter within 10 seconds, Blob will automatically start the Linux kernel:
Starting kernel ... |
However, if you press Enter, you will see the Blob prompt:
Autoboot aborted |
Blob comes with a selection of useful commands. Type help for a list or refer to Table 6-1.
Table 6-1. Blob Commands
| Command with Options | Explanation |
|---|---|
| boot [kernel options] | Boot Linux with kernel options |
| clock PPCR MDCNFG MDCAS0 MDCAS1 MDCAS2 | Experimental speed setting option - USE WITH CARE! |
| download {kernel|ramdisk} | Download kernel or RAMdisk image to RAM |
| flash {kernel|ramdisk} | Copy kernel or RAMdisk from RAM to flash |
| help | Get this help |
| reload {kernel|ramdisk} | Reload kernel or RAMdisk from flash to RAM |
| reset | Reset terminal |
| speed | Set download speed |
| status | Display current status |
Compiling Blob
Note that two versions of pre-compiled Blobs are provided on the CD and the LART website so most people will not need to compile Blob until you want to modify it or perhaps get a newer version. Should you need to, here are the details. First you need a suitable GNU toolchain:
A native ARM/StrongARM Linux system with gcc 2.95.2, and binutils 2.9.5.0.22 or better
Or any UNIX system with cross compiling binutils 2.9.5.0.22 (or better) and gcc 2.95.2 installed
GNU make (although some vendor supplied make utilities will do)
Next you need to get the software, then configure and compile it. The lastest version available at the time of writing is blob 1.0.8-pre2.tar.gz which is on the CD in /tools/blob/
This example assumes you will unpack it in /usr/src
cd /usr/src
tar -xzvf /cdrom/tools/blob/blob 1.0.8-pre2.tar.gz
cd blob-1.0.8-pre2
Now you need to specify the board for which you want to compile it, and whether you are cross-compiling or not, i.e. if you are compiling on a PC rather than a native ARM machine. There are currently four valid board names, choose from: 'assabet', 'brutus', 'lart', or 'pleb'. If the board name is omitted, lart will be choosen as a default. If you are modifying Blob itself then you should turn on the --enable-maintainer-mode flag. This will automatically regenerate Makefiles and configure scripts if you change the source files. You need autoconf (>= 2.13) and automake (>= 1.4) installed for this feature.
export CC=/path/to/cross/gcc
export OBJCOPY=/path/to/cross/objcopy
./configure --with-linux-prefix=/path/to/armlinux/source --with-board=boardname
So on our example host machine the correct runes are as follows (this machine needs to be told the host type, otherwise configure complains):
export CC=arm-linux-gcc
export OBJCOPY=arm-linux-objcopy
./configure --with-linux-prefix=/usr/src/arm-linux/linux/ --with-board=lart --host=i386
If things have worked you should get confirmation text like this:
Target board lart |
For a native ARM machine it's much simpler - all you should need is this:
./configure --with-board=lart
So, now you just make Blob with:
make
This will result in a blob-elf32 which is the full executable with headers and a stripped binary blob in the blob-1.0.8-pre2/src/ directory. The much smaller blob is the one you actually upload. blob-elf32 is useful for examining the code produced. The best way to upload Blob to you device is using the appropriate version of JFlash-linux.
Resources
In addition to the Blob-related resources which are available on our CD, you can find:
the Blob source and pre-compiled binaries http://www.lart.tudelft.nl/lartware/blob and on the CD.
JTAG and Jflash-linux
Uploading can be achieved via the JTAG port using software such a Jflash and Jflash-linux. Usage for Windows or GNU/Linux host is essentially identical. The examples given here use GNU/Linux syntax.
Using JTAG and Jflash-linux
In order to use the JTAG programmer, you need to connect the parallel port of your computer to the JTAG port of the device you want to program. The details of this vary from device to device - see the relevant install chapter. Ensure the device is powered up. Jflash and Jflash-linux both autosense for available parallel ports so it shouldn't matter where you plug it in.
You can then issue the following command as root:
./Jflash-linux blob-1.0.7b
and you should see something like the following (this example is using the blob-1.08-pre2 binary on the CD on a LART). After uploading the device will reset itself before running Blob.
using printer port at 378 |
Note: If something is wrong you will see error messages like the following:
error, failed to read device ID |
or
error, failed to read device ID |
or
error, failed to read device ID |
There are a number of possible causes. If you get all 1's then you maybe using the wrong parallel port, or the cable or dongle is not plugged in, or the device is not powered up. If you get all zeros then you may be using the wrong version of JFlash-linux, or (on a LART) you may be suffering from the 'JTAG reset problem', see the section called LART JTAG reset problem in Chapter 3. If you get random numbers some of the time and zeros the rest of the time then you are almost certainly using the wrong version of JFlash-linux.
Angel and Angelboot
Angel and Angelboot together make a simple but effective boot loader that can upload a kernel and RAMdisk to a target device from a host then run them. Angel is the code that lives on the device that gets started on boot and Angelboot is the program that runs on the host and manages the upload. Angel is in fact part of the ARM SDT and can be used as a debugger in that environment. Angelboot allows it to be used outside this environment.
The Windows Jflash code 'SA-1110 Development Board, JTAG Programming Software v0.3' to give it its full title, can be downloaded from: http://developer.intel.com/design/strong/swsup/SA1110Jflash.htm whilst Jflash-linux is obtainable from: ftp://ftp.netwinder.org/users/n/nico/SA1110Jflash.tgz.
Configuring Angelboot
Copy dot.angelrc and Angelboot from the CD to your development directory and rename dot.angelrc to .angelrc. .angelrc is now classified as a hidden file so your filer may hide it from you. You will however, need to edit .angelrc to match your device. so that it has the following settings:
This is an example for an Assabet board
base 0xc0008000 |
The meaning of these settings is as follows:
The base address is the address in target memory that the kernel is loaded to. The file loaded is zImage in the current directory;
entry is the address in target memory that gets jumped to when the loading is complete. For the kernel this is normally the same as the load address;
r0 is what will be in register r0 when the kernel is started - this is normally zero;
r1 is what will be in register r1 when the kernel is started - this is normally the architecture number for the device;
device is the device to use for the upload - normally a serial port such as /dev/ttyS0;
options are the serial port settings to use after the upload is complete - these should match your minicom settings;
baud is the serial speed to use for the upload;
otherfile is the name of a second file to upload - normally the RAMdisk;
otherbase is the address in target memory that otherfile is loaded to;
exec allows a command to be executed once the upload is completed - normally starting your serial communication program.
Runing Angelboot
Make sure your device is ready and that the serial port is connected. Run:
./angelboot
Angelboot will run using the config in .angelrc. You should see the following:
Initialising execution environment. |
Downloading other image size 0x26935d to 0xc0800000 |
Obvisouly the sizes and number of lines of dots and stars vary with the size of the uploaded images and the target addresses are what you specify in .angelrc.
The device should now be running, booting the kernel and using the RAMdisk as the root filing system. If you specified an exec line to run your serial program then it will start and show you the kernel boot info and login prompt.
Chapter 7. Tools and Techniques
Patching
This is the process of modifying a set of files with a 'patch' file containing a list of differences between two sets of files. This is how changes to source code are normally distributed. Patch files are generated by the diff command. You need at least version 2.5 of patch for patching the kernel. Here we use patching the binutils source as an example.
A patch is normally downloaded as a gzipped patch file (denoted by it ending in .gz). If so, gunzip it:
gunzip binutils-patch.gz
You can now patch binutils. Go into your unpacked binutils source directory, and run patch with your downloaded patch file, with argument -p1:
cd /usr/src/binutils-version
patch -p1 < binutils-patch
If you aren't sure exactly how a patch should be applied then the --dry-run option is very useful. Adding this means that patch will do its work, giving all the usual output but no changes are made to the files. To check out the effects of the above patch command, for example, you do:
patch -p1 --dry-run < binutils-patch
You should see a plethora of messages like:
Hunk #1 succeeded at 112
After patching has finished, you can check whether things have worked by searching for files ending in .rej (rejected patches):
% find . -name '*.rej'
In theory, there should be none of these files; all of the patches should have succeeded. However, if there are one or two failed files, it doesn't necessarily mean it won't build especially if the failed files are documentation or have names like README or endings like .info or .texi.
If you have several of these files, however, it could indicate something seriously wrong, and that it won't build. Check that the version of the source the patch is intended to be applied to matches the version of code you have. Also sometimes patches are 'reversed' - i.e. they have the original and modified source version the wrong way round in the diff command that generated the patches. Patch is smart and if it looks like this is the case it will offer to do them all 'backwards' for you.
The -p1 in the above example refers to how many directory '/' separators patch should strip off the filenames before patching. This is to allow for differences in the depth of nesting between the source tree the patch was created on and the one it is being applied to. Normally you will find that -p1 or -p0 is correct. If a patch doesn't seem to work then looking at the depth of filename nesting in it and using a different -p option is the first thing to try.
Once you understand how this works you can save some commands by combining the unzipping and patching commands into one line like this:
zcat binutils-patch.gz | patch -p1
or, if the patch you have is bzipped instead of gzipped, then do:
bzcat binutils-patch.bz2 | patch -p1
Compiling a Kernel
Obtaining the Kernel Source
To compile your own kernel you need the source and the right set of patches. For all cases you need the base source tree and the ARM kernel patch. The SA1100 patches are usually a good idea too, and are necessary for SA1100 or later processors. For some devices, especially newly-supported ones, you may need a further patch for that device.
- Base source tree
linux-2.4.1-tar.bz2
or linux-2.4.1-tar.gz
- ARM kernel (Russell King) patch
patch-2.4.1-rmk1.gz
- SA1100 (Nico Pitre) patch
diff-2.4.0-rmk1-np2.gz
Kernel Source
Each applied patch adds a suffix to the kernel name, so a kernel made with the 2.4.1 source with the rmk1 ARM kernel patch and the np2 SA1100 patch would be called zImage-2.4.1-rmk1-np2. The letters indicate the patch source. In the above cases they are the names of the patch maintainers Russell King and Nico Pitre respectively. Note that although they use different naming conventions, both patch files are of the same type.
The kernel source is normally available in both gzipped and bzip2 form. The latter is significantly smaller so that is normally the better one to download. You will need the bzip2 utility to decompress bzip2 files.
All these are on the CD but you will need to copy them into your development directory. Alternatively, obtain the latest version of kernel base, ARM kernel and SA1100 patches from these ftp sites but remember to use your local mirror, e.g. ftp://ftp.uk.kernel.org/ for the UK mirror.
- Kernel Base
- ARM kernel Patch
ftp://ftp.arm.linux.org.uk/pub/linux/arm/source/kernel-patches/v2.4/
- SA1100 Patch
Kernel Source - Current Version
The source tree can then be unpacked into your development source directory. You can put this anywhere you like, but it must be kept separate from your native source tree in /usr/src/linux. This is because many systems expect the version of headers in /usr/src/linux to correspond to the version of the kernel and glibc being run on the host machine. This is usually different from the version you are using for ARMLinux development. We recommend putting your ARM kernel source tree in /usr/arm-linux/linux (this is alongside the toolchain in a cross-compilation environment). Note that you need a fair amount of disk space free. The unpacked 2.4.1 source is a little over 100MB, and you should have two copies of it, and configuring and compiling only makes it bigger.
In your development directory enter the following command to unpack the source:
tar -xzvf linux-2.4.1.tar.gz
Or if you have the bzipped version, use these options:
tar -xIvf linux-2.4.1.tar.bz2
Finally, unzip/untar the source before applying the ARM and SA1100 patches to give you a new kernel source tree. Using patch -p0 can confuse various versions of patch so its best to cd into the linux directory and use p1, thus:
cd linux
zcat ../patch-2.4.0-rmk1.gz | patch -p1
zcat ../diff-2.4.0-rmk1-np2.gz | patch -p1
Kernel source mangement
If you are intending to work on the kernel, the first thing you should do is take a copy of the pristine tree. This is so that you can generate patches against it after you have made changes. The simplest way to do this is simply to do:
cp -a linux linux-2.4.1.orig
However, as in practice you will only ever change a few files and having two copies of the whole thing, 99% of which are going to remain untouched, means that you may prefer to use hard links to create the copy as then only the changed files take up space. This method relies on the editor creating a new file after every save so that the original is preserved. If you have need of such an editor, take a look at MicroEmacs or GNU Emac's back-up-when-copying-when-linked facility. To create a hard-linked source copy do this:
cp -a -l linux linux-2.4.1.orig
Alternatively, you can use CVS to control your source versions, but that is not covered here.
Making a Kernel
First you should tidy up the source to get rid of old files and stale dependencies, especially if you have previously configured for a different device with make mrproper. You should then issue the appropriate make target-device_config command to set up a default configuration file for your target device. The list of possibilties for target-device is found in linux/arch/arm/def-configs/. You will then need to set up a kernel configurations file using the defaults which have just been created. This can be accomplished with the make oldconfig command. Finally, make dep sets up kernel dependencies and sub-configuration files on the basis of the specified config whilst make zImage builds the kernel image. The kernel should consequently appear in linux/arch/arm/boot/zImage. So, to summarise:
make mrproper
make target-device_config
make oldconfig
make dep
make zImage
Making a RAMdisk
The RAMdisks that are available for popular devices are usually fine for getting started, but sooner or later you will need to make our own. The steps involved are:
Put all the files you want to put on the disk in a suitable directory with the correct directory structure;
Zero out a block of memory (this is so that the spare space in your RAMdisk compresses as much as possible - if it was full of whatever random stuff was in ram at th time it would waste space in the final RAMdisk);
Make a filesystem in this memory;
Mount it;
Copy the files you prepared into it;
Unmount it;
Compress it.
So here's an example. The size of the RAMdisk is 2MB, your prepared files are in the directory preparedfiles, and we are making a conventional ext2 RAMdisk, rather than something more exotic. /mnt/ramdisk should already have been created as a mount point. You will need to be root.
dd if=/dev/zero of=/dev/ram bs=1k count=2048
mke2fs -vm0 /dev/ram 2048
mount -t ext2 /dev/ram /mnt/ramdisk
cp -av preparedfiles /mnt/ramdisk
umount /mnt/ramdisk
dd if=/dev/ram bs=1k count=2048 | gzip -v9 ramdisk.gz
The -m0 option to mke2fs specifies that no extra space for the super-user is reserved - again to minimise the size of the filesystem.
Looking at existing RAMdisks
To see what is in an existing RAMdisk you need to gunzip it and loop-mount it as a filesytem. Your kernel need loop support for this to work, but a desktop kernel will nromally have this (it's really useful). Lets say you have a RAMdisk called ramdisk_ks.gz (from the Assabet distribution). It's a good idea to work on a copy of the disk, not the original. Do this (/mnt/ramdisk should already have been created as a mount point and you will need to be root):
gunzip ramdisk_ks.gz
mount -o loop ramdisk_ks /mnt/ramdisk
Now you can see the contents by browsing /mnt/ramdisk like any other filesystem. You can even add files by copying them in if there is space left in the RAMdisk. The kernel needs to have support for the filesystem used in the RAMdisk.
Making your own patches
When you have changed some bit of the kernel, e.g. supported a new device or fixed a bug, you need to make a patch of your changes in order to distribute it to others and put it back in the kernel. This is easy to do. Say you have the patched version of the kernel in linux and the original version in linux.orig, then issue these commands.
make mrproper
diff -urN linux.orig linux > my_changes.diff
The make mrproper tidies up all the extra files lying around so that the diff is only of the actual relevant files. Note that the order of the linux.orig and linux arguments above is significant. If you do it the wrong way round you will have made a 'reversed' patch, which is at best confusing. You now have linux/ and linux.orig/ as well as a patch - my_changes.diff. You may now want to rename linux/ to linux.orig so that future patches do not duplicate the chages thus far - this enables each patch to be specific to a change, rather than monolithic. This helps the kernel maintainer (see below).
Russell King maintains an automated 'Patch State System' on his website at http://www.arm.linux.org.uk/developer/patches/ which tracks patches applied to the ARM Linux kernel. It is intended that all ARMLinux developers who wish their patch to be integrated into the ARMLinux kernel (aka -rmk kernels) should submit their patch to this system. These patches will then find their way to Linus.
However, this does not give the full story of patches applied; changes that go into Linus kernels are outside the scope of this patch system.
Please note that by submitting a patch or code to the patch system, you implicitly agree that it is suitable for redistribution with the kernel source. In other words, it is up to you to ensure that the material you submit to the patch system is suitable for inclusion in my kernel, and Linus' kernel. If you have any doubts about this point, please discuss it with Russell in private email.
There are certain restrictions on the system, so please follow these instructions carefully.
Sending in a patch
If you wish to send in a patch, please use the following procedure. It contains some important points that need to be followed:
Generate the patch. Please tell diff to generate unified patches, recursing and new files if necessary. The options are diff -urN. Also, please generate them using a path relative to the directory directly above the main linux/ source tree. If you only want a small area of the kernel, then use diff -urN linux.org/arch/arm/kernel linux/arch/arm/kernel. In the extremely rare case that you absolutely must generate the patch using a different path, please make this obviously visible in the textual part of the patch mail (not following this will result in delays with application of your patch).
Give the mail a descriptive subject line. This will appear on the web page, and in the release notes for the next -rmk version of the kernel.
Include some text in the message explaining what the new feature is, the bug, or why the patch is needed.
Put on a blank line "PATCH FOLLOWS". There must be no space before or after these words on this line.
On a separate line, add a tag "KernelVersion: " followed by the kernel version that the patch was generated against.
Append your patch as plain unwrapped text after this line to the end of the message. Note that the patches must be precisely what diff generates. It is not acceptable for TABs to be converted to spaces, or extra newlines or spaces to be added into the file. If you are unsure about the behaviour of your mailer, send the patch to yourself and examine it.
Mail it to <patches@arm.linux.org.uk>
When you receive a reply, you may wish to supply a detailed follow up article that explains exactly what your patch does. You can do this by replying to the mail you receive from the patch system.
If at any other time you wish to follow up on the patch, please use the subject line as the key (it should include the exact string "(Patch #number)", where 'number' is the patch number that you wish to follow up to).
Please absolutely do not send MIME encoded emails, even quoted-printable MIME encoded emails to the above address. If quoted-printable emails are sent, then you will receive an error message. All mails to <patches@arm.linux.org.uk> should be plain unwrapped text.
Advice
If you have developed a device driver that uses a major/minor pair, please get it allocated according to the linux/Documentation/devices.txt file. Major/minor numbers are device driver specific, not device specific. Any device driver which re-uses major/minor numbers without an extremely good reason (included along with the patch) do not stand any chance of being accepted.
To ease the problems of applying patches, I recommend that you send a patch that adds exactly one feature or bug fix in a single email. Mails containing zero or less, or two or more features stand a greater chance of not being applied if any one part of the patch is not acceptable for some reason.
Patches that are inter-dependent should not be sent - these significantly increase the probability of both patches being rejected, unless both get applied at the same time. My recommendation is: don't do it.
All patches should be complete, that is applying it should not cause any breakage. i.e., adding a new architecture inline function in include/asm-arm/arch-* should be done such that all existing architectures will still at the very least compile correctly. If you're not sure how it should be handled on a particular architecture, put in a GCC #warning statement.
Chapter 8. The GNU Toolchain
This chapter contains information on building a GNU toolchain for ARM targets.
Toolchain overview
The toolchain actually consists of a number of components. The main one is the compiler itself gcc, which can be native to the host or a cross-compiler. This is supported by binutils, a set of tools for manipulating binaries. These components are all you need for compiling the kernel, but almost anything else you compile also needs the C-library glibc. As you will realise if you think about it for a moment, compiling the compiler poses a bootstrapping problem, which is the main reason why generating a toolset is not a simple exercise.
This chapter contains information on how the toolchain fits together and how to build it. However, for most developers it is not necessary to actually do this. Building the toolchain is not a trivial exercise and for most common situations pre-built toolchains already exist. Unless you need to build your own because you have an unusual situation not catered for by the pre-built ones, or you want to do it anyway to gain a deeper understanding, then we strongly recommend simply installing and using a suitable ready-made toolchain.
Pre-built Toolchains
This CD contains three pre-built toolchains, one from emdebian.org, one from the LART project and a third from compaq's handhelds.org team. The emdebian chain is newest, and we've had good sucess with it, but all are used by various people. They all have very similar functionality.
At the moment the most likely situation where a pre-built toolchain will not do the job is if you need Thumb support, in which case you need to use gcc v3 (not yet released at the time of writing, but available as snapshots).
Native Pre-built Compilers
For binary versions of native compilers (ie ones that run on ARM and compile for ARM), the current stable release is on the Aleph ARMLinux CD. You can also get them from:
Resources
The current stable release on Debian's master FTP site (armv3l and above).
The latest release on Debian's master FTP site (armv3l and above).
Sometimes ARMLinux.org will have experimental versions available.
Emdebian
The emdebian version includes gcc version 2.95.2, binutils 2.9.5.0.37, and glibc 2.1.3. Installation is simple. If you have a Debian system then the emdebian cross-compiler is incredibly simple to install - just show apt the directory on the CD and do apt-get install task-cross-arm. What could be simpler?
| Warning |
The emdebian cross development environment will install files in /usr/bin so you will have to make sure that you do not overwrite any development tools which you may already have on your system. |
Installing the Toolchain
task-cross-arm is a virtual package which includes:
gcc version 2.95.2;
binutils 2.9.5.0.37;
glibc 2.1.3.
This is made up of the following packages:
the C preprocessor: cpp-arm_2.95.2-12e4_i386.deb;
the C compiler: gcc-arm_2.95.2-12e4_i386.deb;
the C++ compiler: g++-arm_2.95.2-12e4_i386.deb;
gnu C library: libc6-dev-arm_2.1.3-8e4_i386.deb;
C++ library: libstdc++2.10-arm_2.95.2-12e4_i386.deb;
C++ library and headers: libstdc++2.10-dev-arm_2.95.2-12e4_i386.deb;
Binary utilities: binutils-arm_2.9.5.0.37-1e3_i386.deb.
They are available in both deb and RPM form.
In order to set up your cross development environment on a Debian system, proceed as follows:
su to root by typing su at the prompt;
add the line
deb http://www.emdebian.org/emdebian unstable main
to your /etc/apt/sources.list file;type apt-get update to tell apt/dselect to note the new packages available ;
enter apt-get install task-cross-arm to install your new development environment;
type exit to become a normal user and begin to cross-compile.
For the RPM form download it and use:
rpm -i g++-arm-1%3a2.95..2-12e4.i386.rpm
LART
The LART tarball contains:
gcc 2.95.2;
binutils 2.9.5.0.22;
glibc 2.1.2.
Installing the Toolchain
In order to install the LART tarball on your system, do the following:
mkdir /data
mkdir /data/lart
cd /data/lart
bzip2 -dc arm-linux-cross.tar.bz2 | tar xvf -
You can then add /data/lart/cross/bin to your path. The C and C++ compilers can then be invoked with arm-linux-gcc and arm-linux-g++ respectively.
Compaq
The Compaq arm-linux cross toolchain includes:
gcc-2.95.2;
binutils-2.9.5.0.22;
glibc-2.1.2 with the international crypt library.
The toolchain is compiled with a i386 host with an armv41 target.
Installing the Toolchain
Note: The toolchain must be installed in /skiff/local as it will not work from any other path.
The only other problem that you may have with the include files is that the tarball was set up for Linux 2.2.14. You may consequently need to set up symbolic links:
ln -s /usr/src/linux/include/asm
/skiff/local/arm-linux/include/asm
ln -s /usr/src/linux/include/linux
/skiff/local/arm-linux/include/linux
Alternatively, copy /usr/src/linux/include/asm and /usr/src/linux/include/linux to /skiff/local/arm-linux/include before running make menuconfig and make dep. This will verify that your kernel tree and correct symbolic links are up to date.
Note: This toolchain has glibc symbol versioning. If you are using a NetWinder, you may have to compile your code with static libraries.
Building the Toolchain
In outline what you need to do is:
Decide on the target name;
Decide where to put the images;
Work out headers policy;
Compile binutils first;
Then compile gcc;
Produce gLibc last.
Picking a target name
A native compiler is one that compiles instructions for the same sort of processor as the one it is running on. A cross-compiler is one that runs on one type of processor, but compiles instructions for another. For ARM embedded development it is common to have a compiler that runs on an x86 PC but generates code for the target ARM device.
What type of compiler you build and the sort of output it produces is controlled by the 'target name'. This name is what you put in instead of 'TARGET-NAME' in many of the examples in this chapter. Here are the basic types:
- arm-linux
This is the most likely target you'll want. This compiles ELF support for Linux/ARM (i.e. standard ARMLinux). ELF is the best and most recent form for binaries to be compiled in, although early Acorn Linux/ARM users may still be using the old 'a.out' format.
- arm-linuxaout
This produces Linux/ARM flavour, again, but using the 'a.out' binary format, instead of ELF. This is older, but produces binaries which will run on very old ARMLinux installations. This is now strongly deprecated; there should be no reason to use this target; note that binutils 2.9.5 doesn't contain support for it (refer to the section called Issues with older version of binutils and gcc).
- arm-aout, arm-coff, arm-elf, arm-thumb
These all produce flat, or standalone binaries, not tied to any operating system. arm-elf selects Cygnus' ELF support, which shares much of its code with arm-linux.
You can fiddle with the arm bit of the target name in order to tweak the toolchain you build by replacing it with any of these:
- armv2
This makes support for the ARM v2 architecture, as seen in the older ARM2 and ARM3 processors. Specifically, this forces the use of 26-bit mode code, as this is the only type supported in the v2 architecture.
- armv3l, armv3b
This makes support for the ARM v3 architecture, as seen in the ARM610, and ARM710. The l or b suffix indicates whether little-endian or big-endian support is desired (this will almost always be little-endian).
- armv4l, armv4b
This makes support for the ARM v4 architecture, as used in the StrongARM, ARM7TDMI, ARM8, ARM9.
- armv5l, armv5b
This makes support for the ARM v5 architecture, as used in the XScale and ARM10.
In practice the target name makes almost no practical difference to the toolchain you get anyway so you should always use plain 'arm'. This means that the toolchain itself is not unhelpfully tied to the type of processor it was built on. You get a toolchain that will run on all ARM processors and you can set the compiler output for the target processor when you build each part of the toolchain.
Choosing a directory structure
In many of the shell commands listed in this document you'll see italicised and emboldened bits of text. These are, on the whole, directory paths which will change depending on exactly how you've configured your toolchain. This means that we have not used an actual directory path in examples as it could be different from your setup. You need to substitute the correct value for your setup yourself for any commands that we have listed in this document.
Here is a list of these items:
- PREFIX
This is the base directory containing all the other subdirectories and bits of your toolchain; the default for any system is almost always /usr, so unless you have a particular desire to put your toolchain in /usr/local, or /usr/arm/tools or somewhere else (to keep it separate, perhaps), we recommend you use the default, /usr.
- TARGET-PREFIX
If you're building a cross-toolchain, this is equal to PREFIX/TARGET-NAME (e.g. /usr/arm-linux). If you're building a native compiler, this is simply equal to PREFIX.
- KERNEL-SOURCE-LOCATION
This is the place where your kernel source (or at least headers) are stored. Especially if you are cross compiling this may well be different to the native set of files. We recommend that you set this to TARGET-PREFIX/linux as a sensible default.
Binutils
Binutils is a collection of utilities, for doing things with binary files.
Binutils components
- addr2line
Translates program addresses into file names and line numbers. Given an address and an executable, it uses the debugging information in the executable to figure out which file name and line number are associated with a given address.
- ar
The GNU ar program creates, modifies, and extracts from archives. An archive is a single file holding a collection of other files in a structure that makes it possible to retrieve the original individual files (called members of the archive).
- as
GNU as is really a family of assemblers. If you use (or have used) the GNU assembler on one architecture, you should find a fairly similar environment when you use it on another architecture. Each version has much in common with the others, including object file formats, most assembler directives (often called pseudo-ops) and assembler syntax.
as is primarily intended to assemble the output of the GNU C compiler gcc for use by the linker ld. Nevertheless, we've tried to make as assemble correctly everything that the native assembler would. This doesn't mean as always uses the same syntax as another assembler for the same architecture.
- c++filt
The c++filt program does the inverse mapping: it decodes (demangles) low-level names into user-level names so that the linker can keep these overloaded functions from clashing.
- gasp
Gnu Assembler Macro Preprocessor.
- ld
The GNU linker ld combines a number of object and archive files, relocates their data and ties up symbol references. Often the last step in building a new compiled program to run is a call to ld.
- nm
GNU nm lists the symbols from object files.
- objcopy
The GNU objcopy utility copies the contents of an object file to another. objcopy uses the GNU BFD library to read and write the object files. It can write the destination object file in a format different from that of the source object file. The exact behavior of objcopy is controlled by command-line options.
- objdump
objdump displays information about one or more object files. The options control what particular information to display.
- ranlib
ranlib generates an index to the contents of an archive, and stores it in the archive. The index lists each symbol defined by a member of an archive that is a relocatable object file. You may use `nm -s' or `nm --print-armap' to list this index.
- readelf
readelf Interprets headers on elf files.
- size
The GNU size utility lists the section sizes and the total size for each of the object files objfile in its argument list. By default, one line of output is generated for each object file or each module in an archive.
- strings
GNU strings prints the printable character sequences that are at least 4 characters long (or the number given with the options below) and are followed by an unprintable character. By default, it only prints the strings from the initialized and loaded sections of object files; for other types of files, it prints the strings from the whole file.
- strip
GNU strip discards all symbols from the target object file(s). The list of object files may include archives. At least one object file must be given. strip /modifies the files named in its argument, rather than writing modified copies under different names.
Downloading, unpacking and patching
The first thing you need to build is GNU binutils. 2.9.5 versions have proved stable but generally the latest release is recommended (2.10.1 at the time of writing). No-one should be using 2.9.1 anymore.
Download the latest version you can find from any of these sites:
Unpack the archive somewhere handy, like /usr/src:
cd /usr/src
tar -xzf /.../binutils-2.10.1.tar.gz
There may be ARM-specific patches available for binutils which resolve various bugs, or perhaps improve performance; it's usually a good idea to apply these to the source, if they exist. However ARM binutils are now quite stable (at the time of writing) and integrated with the main tree, so extra patches are no longer normally required. The best place to get up to date information is the armlinux-toolchain mailing list.
The place to check if there are any currently recommended patches is here:
If you do need to patch binutils refer to the section called Patching in Chapter 7 for details of the proceedure.
Configuring and compiling
Essentially, you want to follow the instructions provided in the file called INSTALL. In practice you'll probably use one of the followingexamples.
If you're building a native toolchain, i.e. you're building on an ARM machine for an ARM machine, then you should just do this from inside the binutils directory:
./configure --prefix=PREFIX
If you're building on another machine (such as an x86 Linux box), and you want to build a cross-compiler for the ARM, try this:
./configure --target=TARGET-NAME --prefix=PREFIX e.g. ./configure --target=arm-linux --prefix=/usr
This should succeed (i.e. proceed without stopping wit