readme

ARMboot is a firmware monitor/bootloader for embedded systems based on ARM or StrongARM CPUs

#
# (C) Copyright 2002
# SYSGO Real-Time Solutions GmbH
#
# http://www.sysgo.de
# http://www.elinos.com
#
# 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:

    http://www.sourceforge.net/projects/armboot

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:

    http://lists.sourceforge.net/lists/listinfo/armboot-users/

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.