Bootldr

Introduction

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.

Command List

help
The help command lists all the supported commands along with a very brief description of their syntax.
help
help <cmdname>
<cmdname> help
load
The 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
This command will install a new version of the NetBSD or Linux kernel (uncompressed or compressed with gzip).  The kernel file can be up to 30800192 bytes. (3MB - 64KB).
load bootldr
Installs a copy of the bootloader (which may be up to 48KB). Use with extreme caution.   If a non-functional bootloader is installed, the bootloader will have to be reinstalled via the JTAG Test Access Port.
load ramdisk
Installs a copy of the linux initial ramdisk (which may be up to 3MB).  Only for use with Linux.
load params
Installs up to 16KB of boot parameters.  One parameter stored in this section is the serial port baudrate.
load jffs
Installs a Journalling Flash File System image. Only available when JFFS support has been compiled in.
load flash <flashoffset> <size>
This is an advanced command.  Downloads a file to Flash at the indicated offset from the start of Flash.  Erases all the affected sectors. Use with caution, because it is possible to inadvertently overwrite the kernel or ramdisk using this command..
boot
Invokes the operating system.  It automatically detects whether the kernel is gzipped and whether it is Linux or NetBSD.  This command can be used in four ways, the first being the most common:
boot
Invoke the operating system installed in Flash.
boot flash
Invoke the operating system installed in Flash.
boot nfsroot
With Linux installed, this directs it to boot and mount an NFS root filesystem.
boot jffs
Boots a kernel from the JFFS flash partition. See below for details on kernel selection. The special form, boot jffs ? displays a list of available kernels. Only available when JFFS support has been compiled in.
show
Shows the bootloader parameters and their values.  Shorthand for params show
set
Sets bootloader parameters. Use show to see the parameters and their values.
params
params reset
Reset the bootldr parameters to their defaults
params show
Show all the parameters and their values.
params eval
Evaluate all the bootldr commands in the params sector (prefixed with bootldr:, e.g.,
  bootldr: set nfsroot /tftpboot/root.skiff
params save
Saves bootldr parameters to flash (currently overwrites any non-bootldr parameters in the params section.  See load params)
peek jffs
Examines files in the Journalling Flash File System partition. Only available when JFFS support has been compiled in. There are two forms of this command:
peek jffs <inumber>
Sweeps the filesystem and displays raw inodes having the given inode number on the terminal. Does not reconstruct any files, nor does it even initialize the filesystem (if not already initialized).
peek jffs <absolutepath> <length>
Reconstructs the file named by <absolutepath> and displays the first <length> bytes of that file in hexadecimal and ASCII on the terminal.
peek ram
Reads 4 bytes from the specified address (using the bootloader's virtual to physical address mapping) and displays in hexadecimal.
poke ram
Writes 4 bytes to the specified address (using the bootloader's virtual to physical address mapping). This command can crash the system, but it should cause no lasting damage.
eflash
This is an advanced command. Erases the specified sector of Flash.  Use with extreme caution. If the bootldr is erased, then the machine will be unusable.
physaddr
Shows the physical address for the specified virtual address.
ls [<absolutepath>]
Lists information about the file or directory named by the single argument (or the filesystem root, if no argument is given). Only available when JFFS support has been compiled in.
md5sum <absolutepath>
Computes the MD5 message digest of the file named by the single argument. Only available when JFFS and MD5 support have been compiled in.
histogram
Displays a distribution of JFFS or JFFS2 inodes in the flash device.

Bootldr Params

baudrate
This parameter controls the baudrate of the serial port used for communication with the unit. Once the value has been changed, the serial port must be adjusted accordingly on the host side.
boot_type
This specifies the root filesystem when booting Linux.
flash
ramdisk or cramfs in flash
nfsroot
Root filesystem mounted via NFS.
jffs
Journalling Flash File System partition. Only available when JFFS support has been compiled in.
boot_file
This specifies the default boot label or the name of a file to boot from the Journalling Flash File System partition. See below for more information. Only available when JFFS support is compiled in.
conf_file
This specifies the name of a bootldr configuration file on the Journalling Flash File System partition. See below for more information. Only available when JFFS support is compiled in.
download_kernel
If set to a nonzero value, then the boot command will boot a kernel it downloads into DRAM via XMODEM or YMODEM rather than booting the kernel in flash.
kernel_in_ram
If set to a nonzero value, then the boot command will jump to the location specified here rather than copying the kernel image from flash to DRAM and booting it.
force_unzip
No longer used.
noerase
Advanced command. Inhibits the erasing of flash before programming. Assumes flash was manually erased using the eflash command.
override
Advanced command. Use of this command may render the system unusable. Enables any location in flash to be programmed using the load flash command.
entry
Advanced command. The DRAM address into which the kernel is loaded.
copy_ramdisk
Advanced command. Set this to zero when using a cramfs if the bootldr attempts to treat the cramfs image as an initial ramdisk. Also set to zero if using JFFS.
ramdisk_addr
Advanced command. Takes effect when the value of 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.
dcache_enabled
Set to 0 to disable the data cache and to 1 to enable the data cache. This variable does not affect the kernel's choice of whether or not to enable the data cache.
icache_enabled
Set to 0 to disable the data cache and to 1 to enable the instruction cache. This variable does not affect the kernel's choice of whether or not to enable the instruction cache.
maclsbyte
On Skiff, this reports the least significant byte of the ethernet address.
dram_size
Advanced command.This variables shows the autodetected DRAM size and is used to indicate to the kernel how much memory is available.
linuxargs
The command line arguments to pass to the Linux kernel when booting, in addition to any passed on the command line to the boot command.
hostname
When set, is passed on the command line to override Linux IP hostname autoconfiguration via the ip=... option.
ipaddr
When set, is passed on the command line to override Linux IP address autoconfiguration via the ip=... option.
gateway
When set, is passed on the command line to override Linux IP default gateway autoconfiguration via the ip=... option.
netmask
When set, is passed on the command line to override Linux IP netmask autoconfiguration via the ip=... option.
nfs_server_address
When set, is passed on the command line to override Linux IP autoconfiguration via the ip=... option.
nfsroot
When set, is passed on the command line to override Linux IP autoconfiguration via the ip=... option.
verbose
Currently has no effect.
ymodem
When set, serial transfers are performed using the YMODEM protocol. This has the advantage of using a more robust integrity check (CRC16 versus arithmetic sum) during transmission. In addition, if MD5 support has been configured, the MD5 sum of the transferred file is displayed. If this parameter has the value 0 (default), transfers occur using the XMODEM protocol.

Params

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.

Machine Support

Please read the machine-specific notes for your hardware.

Intel Assabet and Neponset

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.

Journalling Flash File System

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.

bootldr.conf

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.

default (G)
Specify the label or alias of the default image to boot.
image
Specify the absolute path of a bootable file in the filesystem. Begins a new image scope block.
label (L)
Specify a name by which this image block will be known. At most one label can be applied per block.
alias (L)
Specify an alternative name by which this image block will be known. At most one alias can be applied per block.
read-only (GL)
Indicate that the root filesystem should be mounted read-only by passing "ro" as a kernel argument. Overrides read-write.
read-write (GL)
Indicate that the root filesystem should be mounted read-write by passing "rw" as a kernel argument.
ramdisk (GL)
Specify the integer size in kilobytes of kernel ramdisks by passing the "ramdisk_size" argument.
root (GL)
Specify the name of the device which contains the root filesystem by passing the "root" kernel argument.
append (GL)
Specify a string of kernel arguments to be appended to any others generated during boot configuration.
literal (L)
Specify a string of kernel arguments to use in place of any others generated during boot configuration. This essentially causes any other keywords to be ignored, and also overrides most bootldr params which would otherwise result in the generation of kernel arguments. Use with caution.

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.

$Date: 2002/02/13 20:36:13 $ $Author: jamey $