#
# (C) Copyright 2002
# SYSGO Real-Time Solutions GmbH
#
#
#
#
# See file CREDITS for list of people who contributed to this
# project.
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License as
# published by the Free Software Foundation; either version 2 of
# the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston,
# MA 02111-1307 USA
Overview
========
ARMboot is a firmware monitor/bootloader for embedded systems based
on ARM or StrongARM CPUs. The primary objectives for this software is
to be easily portable to new platforms while being as powerful as possible.
To date it is the only GPL'ed ARM firmware capable of supporting multiple
types of flash memory, network download via bootp, dhcp, tftp, PCMCIA CF
booting and more.
ARMboot is heavily based on the sister project PPCboot. It is planned, to
move both projects even close together to increase their robustness and
mutual benefit.
Getting ARMboot
===============
ARMboot is hosted on Sourceforge:
The lastest version can always be obtained via the anonymous CVS access of
Sourceforge. Tarballs are released sporadically, and can be downloaded from
the same site.
Mailing List
============
Questions regarding the use and porting of ARMboot should be posted to the
ARMboot mailing list. You can subscibe here:
If you want to get help on a certin issue, please go first to the
mailing list's archive to whether that question has been discussed in the
past.
Building ARMboot
================
To configure and build ARMboot you will need a GNU cross development
tool-chain configured for arm-linux. You should NOT need any linux header
files. If so, please report this on the mailing list.
The cross development tools usually have a target specific prefix. For
instance, your cross compiler may be called "arm-linux-gcc" or
"arm_armv4-gcc". This prefix can be passed to the Makefile by setting the
CROSS_COMPILE variable, which defaults to "arm-linux-".
The following example is for the "LART" board:
1. Configure
sh# make lart_config
rm -f include/config.h include/config.mk
Configuring for lart Board...
2. Build
sh# make all
...
arm_armv4-objcopy -O srec armboot armboot.srec
arm_armv4-objcopy -O binary armboot armboot.bin
Supported Hardware
==================
Board Configuration Notes
--------------------------------------------------------------------------
LART lart_config "Linux ARM Radio Terminal"
SSV DNP1110 dnp1110_config SSV DilNET PC (no flash support)
Shannon shannon_config Tuxscreen (no support for
IrDA keyboard, LCD screen)
implementa impA7 impa7_config EP7211 based
CLEP7312 ep7312_config Cirrus Logic EP7312 Dev. Board
S3C2400X samsung_config Samsung S3C2400X
SMDK2410X smdk2410_config Samsung SMDK2410X Eval Board
EPXA1DB epxa1db_config Altera EPXA1 Development Board
Testing of ARMBoot Modifications, Ports to New Hardware, etc.:
==============================================================
If you have modified ARMBoot sources (for instance added a new board
or support for new devices, a new CPU, etc.) you are expected to
provide feedback to the other developers. The feedback normally takes
the form of a "patch", i. e. a context diff against a certain (latest
official or latest in CVS) version of ARMBoot sources.
But before you submit such a patch, please verify that your modifi-
cation did not break existing code. At least make sure that *ALL* of
the supported boards compile WITHOUT ANY compiler warnings. To do so,
just run the "MAKEALL" script, which will configure and build ARMBoot
for ALL supported system. Be warned, this will take a while. You can
select which (cross) compiler to use py passing a `CROSS_COMPILE'
environment variable to the script, i. e. to use the cross tools from
the ELinOS Toolkit you can type
CROSS_COMPILE=arm_armv4- MAKEALL
Image Formats
=============
The "boot" commands of this monitor operate on "image" files which
can be basicly anything, preceeded by a special header; see the
definitions in include/image.h for details; basicly, the header
defines the following image properties:
* Target Operating System (Provisions for OpenBSD, NetBSD, FreeBSD,
4.4BSD, Linux, SVR4, Esix, Solaris, Irix, SCO, Dell, NCR, VxWorks,
LynxOS, pSOS, QNX;
Currently supported: Linux, NetBSD, VxWorks, QNX).
* Target CPU Architecture (Provisions for Alpha, ARM, Intel x86,
IA64, MIPS, MIPS, PowerPC, IBM S390, SuperH, Sparc, Sparc 64 Bit;
Currently supported: PowerPC).
* Compression Type (Provisions for uncompressed, gzip, bzip2;
Currently supported: uncompressed, gzip).
* Load Address
* Entry Point
* Image Name
* Image Timestamp
The header is marked by a special Magic Number, and both the header
and the data portions of the image are secured against corruption by
CRC32 checksums.
Submitting Patches
==================
Since the number of patches for ARMBoot is growing, we need to
establish some rules. Submissions which do not conform to these rules
may be rejected, even when they contain important and valuable stuff.
When you send a patch, please include the following information with
it:
* For bug fixes: a description of the bug and how your patch fixes
this bug. Please try to include a way of demonstrating that the
patch actually fixes something.
* For new features: a description of the feature and your
implementation.
* A CHANGELOG entry
* A MAINTAINERS entry
* For major contributions, your entry to the CREDITS file
* When you add support for a new board, don't forget to add this
board to the MAKEALL script, too.
* If your patch adds new configuration options, don't forget to
document these in the README file.
* The patch itself. If you are accessing the CVS repository use "cvs
update; cvs diff -puRN"; else, use "diff -purN OLD NEW". If your
version of diff does not support these options, then get the latest
version of GNU diff.
We accept patches as plain text, MIME attachments or as uuencoded
gzipped text.
Notes:
* Before sending the patch, run the MAKEALL script on your patched
source tree and make sure that no errors or warnings are reported
for any of the boards.
* Keep your modifications to the necessary minimum: A patch
containing several unrelated changes or arbitrary reformats will be
returned with a request to re-formatting / split it.
* If you modify existing code, make sure that your new code does not
add to the memory footprint of the code ;-) Small is beautiful!
When adding new features, these should compile conditionally only
(using #ifdef), and the resulting code with the new feature
disabled must not need more memory than the old code without your
modification.
