HOWTO - Use Autoscript in U-Boot

U-Boot's allows users to run a series of commands in the bootloader from a script file. This allows repetitive actions to be run often with little input from the user.

Prerequisites

U-Boot source
PowerPC toolchain

Script format

Scripts can contain any number of commands that are supported in U-Boot. The script format that U-Boot uses includes a binary autoscript header created using the "mkimage" application described in the next few sections.

Script example (this shows the network configuration of U-Boot, "network.script")

network.script

echo
echo Network Configuration:
echo ----------------------
echo Target:
printenv ipaddr
echo Server:
printenv serverip
echo

Script image creation

U-Boot expects autoscript images to have a header. To create the autoscript image with header you must use the U-Boot tools "mkimage" application. U-Boot must be compiled before mkimage can be used. "mkimage" resides in <U-boot_dir>/tools directory - it is recommended that you copy this program into your path somewhere. The command line used to create the autoscript image is as follows:

mkimage -A U- -O linux -T script -C none -a 0 -e 0 -n "autoscript <script_name> script"\
-d <source_script> <destination_image>

Where:

<script_name> describes the nature of the script.
<source_script> is the location of the script text file
<destination_image> is the location for the autoscript image

Script usage

To execute a script first download the autoscript image to RAM.
E.g. tftp 0x100000 example-script.scr
Then to run the script, autoscr 0x100000

Recursive scripts

Autoscript does not run scripts from the offset in RAM specified on the command line. It first copies the header and the body of the autosript image to a dynamically allocated (malloc) area of RAM. This leads to two very nice features. First, autoscript is recursive. Scripts can download and call other scripts. Making scripts atomic can lead to a very powerful and flexible bootloader scheme. Second, RAM can be used freely without worrying about copying images over scripts that are currently executing (provided that scripts do not corrupt the stack and malloc area at the end of RAM). One word of caution, there is no protection of the stack or malloc areas support in U-Boot. It is up to the user to know which areas of RAM can not be used by scripts. (With 16 Megs of RAM, the stack starts at 0x00f9,ff48, but may differ depending on Bootloader size and malloc area size and grows toward 0x0000,0000)

Error handling

If a command within a script returns an error that script will terminate and calling scripts will terminate with an error. There is no error handling and limited flow control using autoscript. It is possible to maintain state through setting of environment variables in the scripts.

Conventions

File suffix for and autoscript image (binary) end in "scr". File suffixes for script text file end with "script".