The bootloader firmware (bootldr) is the program that first gets control of the machine when it is powered on. The bootloader initializes and manages the raw hardware. One of its main jobs is to copy the operating system from non-volatile memory (Flash) to DRAM and pass control to the operating system. The bootloader performs platform specific hardware configuration for the operating system, such as steering interrupts on the PCI devices (on Skiff only).
In addition, the bootloader provides a simple command-line interface that allows the user to download new versions of the operating system, user code, and parameters into Flash via the XMODEM or YMODEM protocols.
The following is the list of bootloader commands.
help
help <cmdname>
<cmdname> help
load
command downloads files into
DRAM or Flash using the XMODEM or YMODEM protocol.
The most common uses of load
are to
install new versions of the kernel, user code, or the
bootloader itself. The syntax for these forms is
shown below:
load
kernel
load
bootldr
load
ramdisk
load
params
load
jffs
load flash <flashoffset>
<size>
boot
boot
flash
boot nfsroot
boot jffs
boot jffs ?
displays a list of available kernels. Only
available when JFFS support has been
compiled in.params show
show
to
see the parameters and their values.params reset
params show
params eval
bootldr: set nfsroot
/tftpboot/root.skiff
params save
peek jffs
<inumber>
peek jffs
<absolutepath>
<length>
boot
command will boot a kernel it downloads into DRAM via
XMODEM or YMODEM rather than booting the kernel in flash.
boot
command will jump to the location specified here rather
than copying the kernel image from flash to DRAM and
booting it.
load flash
command.
copy_ramdisk
is nonzero. Set
this to zero when using a cramfs. If using an ext2
ramdisk, set to the location in RAM where the image
should be located before booting the kernel; for most
SA-1100 systems, this location is
0xc0800000
.
boot
command.
ip=...
option.
ip=...
option.
ip=...
option.
ip=...
option.
ip=...
option.
ip=...
option.
0
(default), transfers occur using the
XMODEM protocol.
The Params region of flash contains customization variables used by the bootldr and kernel. Each line is prefixed by a keyword and colon, indicating the consumer of the data. Users may add their own prefixes and extract the data from flash at runtime using fu, grep, and cut.
The only defined keywords are bootldr and profile. Lines prefixed with "bootldr:" are read and evaluated as bootldr commands beforing booting a kernel. Lines prefixed with "profile:" are read and sourced by the NetBSD .profile.
It is easiest to manage the params section by using the params command described above, but this only works if the bootldr is the only software using the params section.
Please read the machine-specific notes for your hardware.
Support for the Intel StrongARM SA-1110 Microprocessor Development board (Assabet) and the Intel StrongARM SA-1111 Microprocessor Development Module (Neponset) was added on 22 November, 2000.
The Assabet hardware is similar to Bitsy in a number of ways that are relevant to the bootldr, such as memory initialization or the use of SA-1110 on-chip UARTs for serial communication. One special convention which is described in the hardware manuals for the development boards concerns UART selection: when Assabet is used alone, UART1 is the main console serial port. When Neponset is present, UART3 (accessible via port J20 on the companion board) becomes the console port (and the Assabet RS232 transceiver is shut down).
The bootldr is aware of the presence or absence of Neponset when running on Assabet, and configures the appropriate UART. The Linux kernel also respects this convention, and includes the same companion board detection logic. The default bit rate for either UART is 115200bps; make sure that your kernel and userland programs (such as getty) are configured appropriately.
The Assabet bill of materials claims that the board is shipped with Intel 28F128J3A (StrataFlash) flash memories. Some configurations of the board actually include the smaller 28F160B3 boot block flash components, for a total bank 0 size of 4MB. The bootldr includes support for both parts.
When compiling bootldr for Assabet, be
sure to edit the file config.mk
to
include the definition,
CONFIG_ARCH=assabet
.
Support for the Journalling Flash File System (JFFS) was added on 22 November, 2000.
The bootldr provides the ability to access and boot from a JFFS partition on flash memory. This feature can be useful because it permits easy upgrades of the kernel, and because it eliminates the need for a separate kernel partition in the flash device. A user may simply provide the name of the boot image in the filesystem, and the bootldr will construct the file in main memory, then execute it.
JFFS is a log-structured filesystem which is documented on
the handhelds.org Wiki. The log-based nature of
the filesystem requires the bootldr to "replay" a list
of updates to any file before use. The unsorted
sequence of updates on flash necessitates a "scan" of
the device before the filesystem can be accessed. This
scan occurs once during the first filesystem access,
and is not repeated unless the bootldr reprograms the
JFFS partition. Note that the scan is only performed
to determine final file metadata, such as file size or
name; no files are actually reconstructed until asked
for. Once a file is reconstructed (for any reason),
the built file is cached in memory and is not
reconstructed for subsequent accesses. Commands which
cause file reconstruction include
boot jffs
,
peek jffs
(with a pathname
argument), and md5sum
. Note that
peek jffs
with an inode number argument
does not cause any reconstruction to occur.
When writing a JFFS image (such as one constructed
by mkfs.jffs) to the flash memories, it is
recommended that the image be padded with
0xff
bytes out to the size of the
partition. JFFS does not include an end-of-log
delimiter, and can accidentally misinterpret logs left
over from an earlier filesystem at the end of the
device. These "left over" logs can confuse the
bootldr, which will refuse to replay any filesystem it
finds to be inconsistent.
If you suspect that the bootldr has improperly
reconstructed a file, such as a kernel image, use the
md5sum
command to compare against a known
correct message digest. If the digests do not match,
find the inumber of the file by using the
ls
command, and then send the output of
peek jffs <inumber>
to John Dorsey,
along with a text history of the actions which have
been performed on that file.
Support for bootldr.conf was added on 26 November, 2000.
There are two ways to boot a kernel from a
Journalling Flash File System partition: specify a
bootable file in the filesystem, or provide the label
of a boot image block from a configuration file. The
former approach is straightforward; simply set the
bootldr param boot_file
to the absolute
path of a bootable image (or pass the filename to
boot jffs
). The latter approach
offers easier customization, as the entire boot
configuration can be edited while the operating system
is running; only a reboot is necessary to pick up the
changes.
Boot configuration is based on the contents of a
file in the JFFS flash partition. The name of this
file is stored in the bootldr param
conf_file
, and by default has the value
"/etc/bootldr.conf
". The contents of this
file will be familiar to users of lilo, as
the syntax and keywords were all taken directly from
the Linux Loader used on the i386 architecture. Here
is an example file:
default=linux
read-write
image=/boot/zImage-test
label=test
root=/dev/mtdblock1
read-only
literal="noinitrd console=0"
image=/boot/zImage
label=linux
alias=good
root=/dev/mtdblock1
append="console=0"
As with lilo, the configuration file is
partitioned into sections. Any directives up to the
first image
keyword become part of the
global scope, and will apply to any image block unless
overshadowed. Image blocks contain directives which
apply only to the kernel named in the
image
statement. All directives within an
image block are scoped to that image until a new image
block begins with an image
statement.
In general, keywords can appear in either global or
image scope. The exceptions are default
(which can only be global) and literal
(which can only be image-local). When a keyword is
used in both global and image-local scope, the local
value overshadows the global value. The exception is
append
, which simply appends the local
value to the global value when building the kernel
argument list.
Only one directive may appear per line. Other than
this constraint, whitespace is ignored when parsing
the file. (The indentation in the example file is only
used to improve readability.) To preserve spaces (or
the character `=
', which has a special
meaning during tokenization) in string literals,
enclose them in quotation marks.
The boot_file
param can be set to the
label or alias of an image to boot. If this param has
no value, then the first image parsed will be booted
by default, unless another image is specified using
the default
keyword.
The accepted keywords are described below. The legal scopes of each keyword are denoted by G for global, and L for image-local.
ro
" as a
kernel argument. Overrides
read-write
.rw
" as a
kernel argument.ramdisk_size
"
argument.root
"
kernel argument.A list of available image labels or aliases can be
obtained with the command
boot jffs ?
. Comments about the
configuration syntax or the interpreter code should be
sent to John
Dorsey.