Once you have correctly configured your host software and target hardware, establish a terminal connection from your host to the target, using the serial port that connects the two systems.¹ For example, the following command starts a tip session for the second serial port at 9600 bps:

% tip /dev/ttyb -9600

See your BSP documentation for information about the bps rate (Help>Manuals contents>BSP Reference in the Tornado Launcher, or see the file wind/docs/BSP_Reference.html).

You are now ready to turn on the target system power and boot VxWorks.

When you boot VxWorks with the default boot program (from ROM, diskette, or other medium), you must use the VxWorks command line to provide the boot program with information that allows it to find the VxWorks image on the host and load it onto the target. The default boot program is designed for a networked target, and needs to have the correct host and target network addresses, the full path and name of the file to be booted, the user name, and so on.²

When you power on the target hardware (and each time you reset it), the target system executes the boot program from ROM; during the boot process, the target uses its serial port to communicate with your terminal or workstation. The boot program first displays a banner page, and then starts a seven-second countdown, visible on the screen as shown in Figure 2-6. Unless you press any key on the keyboard within that seven-second period, the boot loader will attempt to proceed with a default configuration, and will not be able to boot the target with VxWorks.

To interrupt the boot process and provide the correct boot parameters, first power on (or reset) the target; then stop the boot sequence by pressing any key during the seven-second countdown. The boot program displays the VxWorks boot prompt, as follows:

[VxWorks Boot]:

Figure 2-6:  Boot Program: Communication and Boot Banner Display

To display the current boot parameters, type p at the boot prompt, as follows:

[VxWorks Boot]: p 

A display similar to the following appears; the meaning of each of these parameters is described in the next section. This example corresponds to the configuration shown in Figure 2-7. (The p command does not actually display blank fields, although this illustration shows them for completeness.)

boot device             : ln 
processor number        : 0 
host name               : mars 
file name               : /usr/wind/target/config/bspname/vxWorks 
inet on ethernet (e)    : 90.0.0.50 
inet on backplane (b)   : 
host inet (h)           : 90.0.0.1 
gateway inet (g)        : 
user (u)                : fred 
ftp password (pw)(blank=use rsh) : 
flags (f)               : 0x0 
target name (tn)        : phobos 
startup script (s)      : 
other (o)               : 

To change the boot parameters, type c at the boot prompt, as follows:

Figure 2-7:  Boot Configuration Example

[VxWorks Boot]: c 

In response, the boot program prompts you for each parameter. If a particular field has the correct value already, press RETURN. To clear a field, enter a period ( . ), then press RETURN. If you want to quit before completing all the parameters, type CTRL+D.

Network information must be entered to match your particular system configuration. The Internet addresses must match those in /etc/hosts on your UNIX host, as described in Establishing the VxWorks System Name and Address.

If your target has nonvolatile RAM (NVRAM), the boot parameters are stored there and retained even if power is turned off. For each subsequent power-on or system reset, the boot program uses these stored parameters for the automatic boot configuration.

The VxWorks boot program provides a limited set of commands. To see a list of available commands, type the help command (h or ?) followed by RETURN:

[VxWorks Boot]: ? 

Table 2-3 lists and describes each of the VxWorks boot commands and their arguments.

Table 2-3:  VxWorks Boot Commands

Command		Description
h		Help command--print a list of available boot commands.
?		Same as h.
@		Boot (load and execute the file) using the current boot parameters.
p		Print the current boot parameter values.
c		Change the boot parameter values.
l		Load the file using current boot parameters, but without executing.
g adrs		Go to (execute at) hex address adrs.
d adrs[, n]		Display n words of memory starting at hex address adrs. If n is omitted, the default is 64.
m adrs		Modify memory at location adrs (hex). The system prompts for modifications to memory, starting at the specified address. It prints each address, and the current 16-bit value at that address, in turn. You can respond in one of several ways:
		ENTER: Do not change that address, but continue prompting at the next address.
		number: Set the 16-bit contents to number.
		. (dot): Do not change that address, and quit.
f adrs, nbytes, value		Fill nbytes of memory, starting at adrs with value.
t adrs1, adrs2, nbytes		Copy nbytes of memory, starting at adrs1, to adrs2.
s [ 0 | 1 ]		Turn the CPU system controller ON (1) or OFF (0) (only on boards where the system controller can be enabled by software).
e		Display a synopsis of the last occurring VxWorks exception.
n netif		Display the address of the network interface device netif.

Each of the boot parameters is described below, with reference to the example in 2.6.2 Entering New Boot Parameters. The letters in parentheses after some parameters indicate how to specify the parameters in the command-line boot procedure described in 2.6.6 Alternate Booting Procedures.

boot device

The type of device to boot from. This must be one of the drivers included in the boot ROMs (for example, enp for a CMC controller). Due to limited space in the boot ROMs, only a few drivers can be included. A list of included drivers is displayed at the bottom of the help screen (type ? or h).

processor number

A unique identifier for the target in systems with multiple targets on a backplane (zero in the example). The first CPU must be processor number 0 (zero).

host name

The name of the host machine to boot from. This is the name by which the host is known to VxWorks; it need not be the name used by the host itself. (The host name is mars in the example of 2.6.2 Entering New Boot Parameters.)

file name

The full pathname of the VxWorks object module to be booted (/usr/wind/target/config/bspname/vxWorks in the example). This pathname is also reported to the host when you start a target server, so that it can locate the host-resident image of VxWorks.³

inet on ethernet (e)

The Internet address of a target system with an Ethernet interface (90.0.0.50 in the example).

inet on backplane (b)

The Internet address of a target system with a backplane interface (blank in the example).

host inet (h)

The Internet address of the host to boot from (90.0.0.1 in the example).

gateway inet (g)

The Internet address of a gateway node if the host is not on the same network as the target (blank in the example).

user (u)

The user name that VxWorks uses to access the host (fred in the example); that user must have read access to the VxWorks boot-image file. VxWorks must have access to this user's account, either with the FTP password provided below, or through the files .rhosts or /etc/hosts.equiv discussed in Giving VxWorks Access to the Host.

ftp password (pw)

The "user" password. This field is optional. If you provide a password, FTP is used instead of RSH. If you do not want to use FTP, then leave this field blank.

flags (f)

Configuration options specified as a numeric value that is the sum of the values of selected option bits defined below. (This field is zero in the example because no special boot options were selected.)

0x01		=		Do not enable the system controller, even if the processor number is 0. (This option is board specific; refer to your target documentation.)
0x02		=		Load all VxWorks symbols, instead of just globals.
0x04		=		Do not auto-boot.
0x08		=		Auto-boot fast (short countdown).
0x20		=		Disable login security.
0x40		=		Use BOOTP to get boot parameters.
0x80		=		Use TFTP to get boot image.
0x100		=		Use proxy ARP.

target name (tn)

The name of the target system to be added to the host table (phobos in the example).

startup script (s)

If the target-resident shell is included in the downloaded image, this parameter allows you to pass to it the complete path name of a startup script to execute after the system boots. In the default Tornado configuration, this parameter has no effect, because the target-resident shell is not included.

other (o)

This parameter is generally unused and available for applications (blank in the example). It can be used when booting from a local SCSI disk to specify a network interface to be included.

Once you have entered the boot parameters, initiate booting by typing the @ command at the boot prompt:

[VxWorks Boot]: @ 

Figure 2-8 shows a typical VxWorks boot display. The VxWorks boot program prints the boot parameters, and the downloading process begins. The following information is displayed during the boot process:

• The boot program first initializes its network interfaces .

• While VxWorks is booting, you can see the size of each VxWorks section (text, data, and bss) as it is loaded .

• After the system is completely loaded, the boot program displays the entry address and transfers control to the loaded VxWorks system .

• When VxWorks starts up, it begins just as the boot ROM did, by initializing its network interfaces; the network-initialization messages appear again, sometimes accompanied by other messages about optional VxWorks facilities.

After that point, VxWorks is up and ready to attach to the Tornado tools, as discussed in 2.7 Connecting a Tornado Target Server.

Figure 2-8:  VxWorks Booting Display

The boot display may be useful for troubleshooting. The following hints refer to Figure 2-8. For more troubleshooting ideas, see 2.10 Troubleshooting.

If the initial "Attaching network interface" is displayed without the corresponding "done," verify that the system controller is configured properly and the Ethernet board is properly jumpered.

If "Loading..." is displayed without the size of the VxWorks image, this may indicate problems with the Ethernet cable or connection, or an error in the network configuration (for example, a bad host or gateway Internet address).

If the line "Starting at" is printed and there is no further indication of activity from VxWorks, this generally indicates there is a problem with the boot image.

If "Attaching network interface" is displayed without the "done," this may indicate there is a problem with the network driver in the newly loaded VxWorks image.

To boot VxWorks, you can also use the command line, take advantage of non-volatile RAM, or create new boot programs for your target.

Command-Line Parameters

Instead of being prompted for each of the boot parameters, you can supply the boot program with all the parameters on a single line at the boot prompt ([VxWorks Boot]:) beginning with a dollar sign character ("$"). For example:

            $ln(0,0)mars:/usr/wind/target/config/bspname/vxWorks e=90.0.0.50 h=90.0.0.1 u=fred

The order of the assigned fields (those containing equal signs) is not important. Omit any assigned fields that are irrelevant. The codes for the assigned fields correspond to the letter codes shown in parentheses by the p command. For a full description of the format, see the reference entry for bootStringToStruct( ) in bootLib.

This method can be useful if your workstation has programmable function keys. You can program a function key with a command line appropriate to your configuration.

Nonvolatile RAM (NVRAM)

As noted previously, if your target CPU has nonvolatile RAM (NVRAM), all the values you enter in the boot parameters are retained in the NVRAM. In this case, you can let the boot program auto-boot without having a terminal connected to the target system.

Customized Boot Programs

See 4.7 Configuring and Building a VxWorks Boot Program for instructions on creating a new boot program for your boot media, with parameters customized for your site. With this method, you no longer need to alter boot parameters before booting.

BSPs Requiring TFTP on the Host

Some Motorola boards that use Bug ROMs and that place boot code in flash require TFTP on the host in order to burn a new VxWorks image into flash. See your vendor documentation on how to burn flash for these boards.

You can boot a target that is not on a network most easily over a serial line with the Target Server File System (TSFS). The TSFS provides the target with direct access to the host's file system. Using TSFS is simpler than configuring and using PPP or SLIP.

To boot a target using TSFS, you must first reconfigure and rebuild the boot program, and copy it to the boot medium for your target (for example, burn a new boot ROM or copy it to a diskette). See 4.7 Configuring and Building a VxWorks Boot Program.

Before you boot the target, configure a target server with the TSFS option and start it. See Target-Server Configuration Options.

The only boot parameters required to boot the target are boot device and file name (see 2.6.4 Description of Boot Parameters). The boot device parameter should be set to tsfs. The file name parameter should be set relative to the TSFS root directory that is defined when you configure the target server for the TSFS. You can configure the boot program with these parameters, or enter them at the VxWorks prompt at boot time.

When VxWorks is running, there are several way you can reboot VxWorks. Rebooting by any of these means restarts the attached target server on the host as well:

• Enter CTRL+X from the Tornado shell or a target console. (You can change this character to something else if you wish; see 5.7 Tcl: Shell Interpretation.)

• Invoke reboot( ) from the Tornado shell.

• Press the reset button on the target system.

• Turn the target's power off and on.

When you reboot VxWorks in any of these ways, the auto-boot sequence begins again from the countdown.

1:  Commonly available terminal emulators are tip, cu, and kermit; consult your host reference documentation.

2:  Unless your target CPU has nonvolatile RAM (NVRAM), you will eventually find it useful to build a new version of the boot loader that includes all parameters required for booting a VxWorks image (see 4.7 Configuring and Building a VxWorks Boot Program). In the course of your developing an application, you will also build bootable applications (see 4.4 Creating a Bootable Application).

3:  If the same pathname is not suitable for both host and target--for example, if you boot from a disk attached only to the target--you can specify the host path separately to the target server, using the Core file field (-c option). See 3.5 Managing Target Servers.