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 a description of the bootloader commands.
Searches for keyword in help descriptions.
The help command lists all the supported commands along with a very brief description of their syntax.
Performs a soft reset. This command is useful for jumping to a new bootldr that has just been installed.
Performs a CPU halt.
Invokes the operating system. It automatically detects whether the kernel is gzipped and whether it is Linux or NetBSD.
Invoke the operating system installed in the default boot location. (See ).
Invoke the operating system installed in the flash partition named kernel_partition. (See Flash.
Boots kernel from JFFS2 partition. This is now the default mode for booting the kernel with Familiar on the iPAQ.
This command first mounts the jffs2 filesystem in flash if it is not mounted.
See the Section called Bootldr Params File for more details on the use of the boot/params file and JFFS2.
boots pocketpc
boots kernel in raw IDE partitions
See the Section called Bootldr IDE Support for more information.
boots kernel in mounted VFAT filesystem
See for more information.
See also the Section called Bootldr Params File for more information.
boots kernel that is stored at specified address in DRAM.
Boots Linux 2.2.x from flash kernel partition, passing in parameters for it to NFS-mount root partition. This command only works on platforms with built in network. It could be made to work with the iPAQ and USB networking.
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.
The load command uses xmodem unless the ymodem parameter is set to a nonzero value. See .
This command will program flash partition named partitionname with the data downloaded data via xmodem.
Unless the noerase parameter is set to a nonzero value, the partition will be erased before new contents are written.
If the partition was defined with flag 16 set, then unused sectors will be marked with the JFFS2 erased block header.
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. See
This is an advanced command. Downloads a data to DRAM at the indicated address. Use with caution, because it could cause the bootldr to hang (not permanently, however).
The bootldr save commands are duals of the load commands. They perform an XMODEM transfer of data from the handheld to a host computer.
Shows the bootloader parameters and their values. Shorthand for params show
Sets bootloader parameters. Use show to see the parameters and their values.
Reset the bootldr parameters to their defaults
With no argument, shows all the parameters and their values. Otherwise, it shows the value for the specified parameter.
Evaluate all the bootldr commands in the params partition
If there is a params partition, then saves bootldr parameters to that partition in flash. (currently overwrites any non-bootldr parameters in the params section.)
This command has no effect unless a params partitions is defined. See the Section called Bootldr Params Partition for more information.
If there is a params partition, then the params save command writes a partition table as a binary object followed by a sequence of set commands to the partition as ASCII text.
To examine the params partition, use the hd command (hexdump -- see ).
add a screen dump of params partitionIf there is no params partition, then the bootldr looks for a file named boot//params in a JFFS2 filesystem. See the Section called Bootldr Params File for details. The bootldr cannot write to this file.
Resets the in-memory partition table to the default. It does not affect the partition table written in flash, if any, nor does it affect the contents of flash. The in-memory partition table is generated on-the-fly if there is no params partition. It may be amended by subsequent partition define or partition delete commands that are read from the file boot/params in a JFFS2 or VFAT filesystem or from the command line interface.
Use the partition save or params save commands to write the partition table to flash.
The default consists of a bootldr partition, and a root partition. On some platforms (H3800), there is also an assets partition that contains the machine's asset tag.
Defines a partition.
The flag value for a bootldr partition is 2.
The flag value for a jffs2 partition is 16. This causes the bootldr to write jffs2 erase-block markers to all the unused sectors when using the load or program command to write to this partition.
The flag value 8, combined with logical-or with one of the above values, indicates that the defined partition extends to the end of flash.
Partitions in the partition table are sorted by starting address.
Deletes the named partition from the DRAM-resident partition table.
Shows the flash partition table.
If there is a params partition, this writes the partition table to the head of the params partition. The params save command will also save the partition table if there is a params partition. (See ).
Reads 4 (or 2 or 1) bytes from the specified address (using the bootloader's virtual to physical address mapping) and displays in hexadecimal.
Reads 4 bytes from the specified offset in flash.
Writes 4 (or 2 or 1) 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.
This command cannot be used to program flash. See the poke flash command.
Programs the flash partition named partname with the contents of the memory region starting at srcaddr and continuing for nbytes bytes.
See for a description of how tags and compressed file content is handled.
This is an advanced command. Erases the specified partition or address range of flash. Use with extreme caution. If the bootldr is erased, then the machine will be unusable.
It will not erase the bootldr partition unless the override parameter is set to nonzero.
If protval is zero, it unprotects all of flash (because it is not possible to unprotect just one sector).
If protval is one, it protects the specified region of flash.
Queries flash using JEDEC CFI flash query. This is an advanced command. Usage will require knowledge of flash interleaving and JEDEC flash commands.
qflash 1 queries size of flash chip.
qflash 2 queries whether sector 0 is locked.
Performs a procedure call or jump to the specified address.
Similar to Unix cat: shows the contents of a file in JFFS2 filesystem.
Displays contents of named address range in hexadecimal. Also displays the characters for printable ASCII values.
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 or JFFS2 support has been compiled in.
Computes the MD5 message digest of the len bytes of memory starting at address napmed by the single argument. Only available when MD5 support has been compiled into the bootldr.
Computes the MD5 message digest of the file napmed by the single argument. Only available when JFFS and MD5 support have been compiled in.
Compares the nbytes of data in DRAM in the memory regions starting at addr1 and addr2
Copies the nbytes of data in DRAM from memory regions starting at srcaddr to dstaddr
Verifies correct operation of DRAM in region from addr1 to addr2.
Shows the physical address for the specified virtual address.
Displays a distribution of JFFS or JFFS2 inodes in the flash device.
Displays the bootldr version number.
Fill LCD bar.
Fills the LCD display with the specified color.
Displays the specified image on the LCD.
Inverts the colors in the frame buffer in the specified region.
Adjusts the LCD front/back light.
Turns off the LCD and front/back light.
Turns on the LCD and front/back light.
Sets the LCD PAL value.
Display gzipped image
Displays the splash screen on the LCD.
Indicates whether any cards are detected
Performs card insertion actions: enables power to socket and binds driver, if available.
Currently, only IDE cards have a driver. IDE cards include CF flash cards, CF hard drives, PCMCIA hard drives, and external IDE drives via PCMCIA adapters.
Performs card ejecting actions: disables power to socket.
Displays card CIS information for debugging purposes.
Performs an IDE identify command on the drive and displays the drive parameters.
For debugging only. ioaddr is the address at which the drive appears in memory.
This command is performed automatically when the pcmcia insert command detects an IDE device.
Reads nbytes of data from the disk, starting at byteoffset, depositing the data in memory starting at dstaddr.
Reads and displays the DOS partition table from the IDE device.
Reads from partition number partitionno, depositing the data in memory starting at dstaddr. If nbytes is unspecified, then reads the whole partition.
Copies nbytes from srcaddr to disk partition partitionno.
Reads the specified sector, depositing the result in memory starting at dstaddr.
As of version 2.18.15, the bootldr can mount, read and boot from FAT16 and FAT32 filesystems mounted on IDE drives.
Currently, long directory entries are ignored and filenames are all lower case.
FAT12, used on small partitions cards, e.g. 7MB, is not supported in bootldr 2.18.24 or newer.
Mounts the FAT32, FAT16, or FAT12 filesystem contained in the specified partition of the attached IDE device. Partition numbering starts at zero.
Lists the specified directory in the mounted vfat filesystem. The directory defaults to root.
Automatically mounts the filesystem.
Copies the contents of the file named filename to DRAM starting at address dstaddr. If len is unspecified, then the whole file is copied.
Automatically mounts the filesystem.
Writes len bytes of data from srcaddr to filename. Adjusts the size of the file but the file named filename must exist.
Automatically mounts the filesystem.
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.
This specifies the root filesystem when booting Linux.
ramdisk or cramfs in flash
Root filesystem mounted via NFS.
Journalling Flash File System partition. Only available when JFFS support has been compiled in.
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.
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.
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.
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.
No longer used.
Advanced command. Inhibits the erasing of flash before programming. Assumes flash was manually erased using the eflash command.
Advanced command. Use of this command may render the system unusable. Enables any location in flash to be programmed using the load flash command.
Advanced command. The DRAM address into which the kernel is loaded.
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.
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.
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.
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.
On Skiff, this reports the least significant byte of the ethernet address.
Advanced command.This variables shows the autodetected DRAM size and is used to indicate to the kernel how much memory is available.
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.
When set, is passed on the command line to override Linux IP hostname autoconfiguration via the ip=... option.
When set, is passed on the command line to override Linux IP address autoconfiguration via the ip=... option.
When set, is passed on the command line to override Linux IP default gateway autoconfiguration via the ip=... option.
When set, is passed on the command line to override Linux IP netmask autoconfiguration via the ip=... option.
When set, is passed on the command line to override Linux IP autoconfiguration via the ip=... option.
When set, is passed on the command line to override Linux IP autoconfiguration via the ip=... option.
Currently has no effect.
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.
The Params partition 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.
A bootldr params file is actually a script executed by the bootldr, usually at startup. It is an ASCII file consisting of one bootldr command per line.
Example 18. boot/params example
set kernel_filename "boot/zimage" set linuxargs "initrd init=/linuxrc root=/dev/hda2 console=ttySA0" |
For example, here is a params file that could be used to boot from a vfat filesystem on an IDE drive. It sets the kernel filename to the all lowercase boot/zimage and also sets the linuxargs.
During the normal bootldr startup sequence (see the Section called Suppression of Params Evaluation), it looks for a params partition. If it finds it, as identified by the presence of a bootldr partition table, then it reads the partition table and evaluates the bootldr commands it finds in the partition.
Note that the params save command can only write to a params partition in flash. If there is no such partition, then params save will print an error message.
If the bootldr did not find a params partition, then it scans flash looking for a JFFS2 filesystem partition. If it finds one, then it mounts the filesystem and looks for the file boot/params. If it finds a boot/params file, then it evaluates the bootldr commands in the file.
The behavior of the bootldr when directed to boot from a VFAT filesystem is very similar -- after mounting the vfat filesytem, it looks for the file boot/params. If it finds such a file it evaluates the bootldr commands in the file.
If the iPAQ was reset while holding the center of the joypad down (see Q: 2.1.), then the normal evaluation of params will be suppressed.
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.
The bootldr now has support for reading from JFFS2 filesystem partitions. Most of what is written in the next section applies to JFFS2. Bootldr binaries on handhelds.org are not compiled with JFFS version 1 support.
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.