It is possible to write your own boot program from scratch, provided that the program leaves a correctly formed boot line at the known memory location and then retrieves, loads, and runs the VxWorks image. While that might sound simple, in practice, it requires a considerable amount of work. This is because the boot program typically needs access to a variety of networking utilities in order to gather all the information needed for the boot line, as well as a file transfer utility to retrieve the boot image.

For example, in many environments, the boot program must include a DHCP client to negotiate for a lease on an IP address. In addition, in order to get the VxWorks image, the boot program typically needs access to a file transfer utility, such as FTP. Thus, such a program must include a network device driver, a DHCP client, a networking stack, an FTP client, and more.

To create a boot program without coding everything from scratch, you can use the appropriate BSP and Tornado to control the configuration of bootConfig.c, the VxWorks boot program. The resulting boot program knows how to format a boot line and store it in the known memory location (as well as NVRAM, if available).¹ However, a boot program that uses the network to retrieve a run-time image needs its own boot parameters, such as the name of its network device.

The default VxWorks boot program has a built-in default boot line.² However, that line might be incomplete, and certain values might not be valid. Before the boot program tries to use its default boot line, the boot program looks in NVRAM, if available. The boot program also accepts a boot line from user input.

From these sources, a non-networked boot program must be able to find appropriate values for all necessary boot parameters. However, if the boot program has network access, the initial boot line needs to define only those parameters required to initialize and use its networking utilities. The boot program can then use these networking utilities to retrieve the missing boot parameters and the run-time VxWorks image from a remote source.

Figure 13-1:  Sources of Boot Parameters

When a VxWorks target boots, it uses the boot line to fill in a BOOT_PARAMS structure. The boot program and the VxWorks run-time image use this structure to track boot parameters. The BOOT_PARAMS structure is defined as follows:

typedef struct                          /* BOOT_PARAMS */ 
    { 
    char bootDev [BOOT_DEV_LEN];        /* boot device code */ 
    char hostName [BOOT_HOST_LEN];      /* name of host */ 
    char targetName [BOOT_HOST_LEN];    /* name of target */ 
    char ead [BOOT_ADDR_LEN];           /* ethernet internet addr */ 
    char bad [BOOT_ADDR_LEN];           /* backplane internet addr */ 
    char had [BOOT_ADDR_LEN];           /* host internet addr */ 
    char gad [BOOT_ADDR_LEN];           /* gateway internet addr */ 
    char bootFile [BOOT_FILE_LEN];      /* name of boot file */ 
    char startupScript [BOOT_FILE_LEN]; /* name of startup script file */ 
    char usr [BOOT_USR_LEN];            /* user name */ 
    char passwd [BOOT_PASSWORD_LEN];    /* password */ 
    char other [BOOT_OTHER_LEN];        /* available for applications */ 
    int  procNum;                       /* processor number */ 
    int  unitNum;                       /* network device unit number */ 
    int  flags;                         /* configuration flags */ 
    } BOOT_PARAMS;

This structure is shown here because its member names provide a convenient set of labels for discussing boot parameters. For example, using the member names shown above, this document can represent the general format of a boot line is as follows:

bootDev(unitNum, procNum) hostName:bootFile e=ead b=bad h=had g=gad u=userName pw=passWord f=flags tn=targetName s=startupScript o=other

The labeled parameters e, b, h, and so on, are not order sensitive. You can leave them blank. For example, "pw= " specifies an empty password parameter. If the labeled parameter is optional or supplied later by DHCP or BOOTP, you can omit it from the boot line entirely.

As an example of a typical boot line, consider the following:

ln(0, 0) bear:/usr/wpwr/target/config/mz7122/vxworks e=90.0.0.2 b=91.0.0.2 h=100.0.0.4 g=90.0.0.3 u=papa pw=biggrump f=0x80 tn=goldilox  
s=bear:/usr/papa/startup o= 

To get a listing of the boot parameters, type p at the boot prompt (if a parameter currently has no setting, the p command does not list it). The labels used in the p listing differ somewhat from the names of the structure members.

Before the boot program can use a DHCP or BOOTP client to retrieve additional boot parameters from a remote server, the boot program needs appropriate values for bootDev, unitNum, procNum, and flags. See Table 13-1. Because the boot program does not yet have network access, the target must be able to find these parameter values in the default boot line, a user-provided boot line, or NVRAM boot line.³

Table 13-1:  Boot Parameters Needed for DHCP, BOOTP, and Network Device Initialization

Parameter Name from BOOT_PARAMS		Parameter Name from p Command Listing (followed by description)
bootDev		boot device Contains the name of the network device to boot from. For example, ln specifies the Lance driver. Which device you specify determines the physical medium over which the boot program attempts a networked boot. Currently, VxWorks supports drivers operating over three physical media: Ethernet, a serial line, and the memory backplane. For information on the configuration needs of these drivers, see 2.2 Data Link Layer Network Components. To add support for another medium, write a MUX-based driver for the new network and include the driver in your boot program. For more information on writing a driver to the MUX interface, see Using the MUX Interface.
unitNum		unit number Contains the unit number for the network device. In boot prompts that reference the network device, the target appends this to the bootDev. For example, if you see an "ln0", the "ln" refers to the Lance driver, and the "0" is the network device unit number. If you do not specify a unit number, the boot program defaults to using 0.
procNum		processor number Contains the backplane processor number of the target CPU. This value is critical to the shared-memory network. The shared memory master must be CPU 0.
flags		flags (f) Contains a value composed of flags (ORed in values) that configure the boot process. The predefined significance of each bit is as follows:
		0x01		Disables system controller for processor 0 (not supported on all boards).
		0x02		Loads the local symbols as well as the global symbols into the target-based symbol table. This has consequences for tools such as the target shell. If the target-based symbol contains local variables, the target shell has access to both locally and globally declared symbols. Setting this bit means you must also reconfigure VxWorks with a downloaded symbol table. The relevant configuration macro is INCLUDE_NET_SYM_TBL. The VxWorks startup code assumes that the file containing the symbol table is resident on the same host as the boot image. The VxWorks startup code also assumes that the name of the symbol table file is the boot file name with an appended .sym suffix. When reading the .sym file, the VxWorks image has the option of loading local symbols as well as global symbols into its target-resident symbol table.
		0x04		Prevents autoboot.
		0x08		Enables quick autoboot (no countdown).
		0x20		Disables login security.
		0x40		Specifies automatic configuration using BOOTP or DHCP. VxWorks tries first to use a DHCP client. If the boot ROM does not include the DHCP client, then the target uses the BOOTP client to retrieve information.
		0x80		Tells the target to use TFTP to get VxWorks image. Otherwise, the target uses either RSH or FTP. The target uses FTP if you enter a non-empty value for the passwd parameter. Otherwise, the target uses RSH.
		0x100		Makes target register as a Proxy ARP client.

If the 0x40 bit in the flags parameter is set, the boot program uses either DHCP or BOOTP client to retrieve the following parameters: ( ) (from which the boot program also derives a value for bad), had, gad, and bootFile.⁴ See Table 13-2.

Table 13-2:  Boot Parameters Returned from DHCP or BOOTP

Parameter Name from BOOT_PARAMS		Parameter Name from p Command Listing (followed by description)
ead		inet on ethernet (e) This value is the Internet address of this target on the Ethernet or, if you are booting from SLIP, the local end of a SLIP connection. You can also specify a subnet mask (as described in Subnet Configuration). If ead is empty, the target does not attach the Ethernet interface. This is acceptable if the target is booting over the backplane.
bad		inet on backplane (b) Actually, neither BOOTP nor DHCP supply this value directly, the backplane Internet address. If this parameter contains a non-empty value, the target attaches the backplane interface. Typically, the boot program uses sequential and proxy default addressing conventions to derive a bad value from the ead parameter (which BOOTP can provide) and the CPU number. However, the use of sequential addressing makes booting from the shared-memory backplane incompatible with DHCP. This parameter should be empty if no shared-memory network is required. To specify a subnet mask for bad, see Subnet Configuration).
had		host inet (h) The Internet address of the host from which to retrieve the boot file.
gad		gateway inet (g) The Internet address of the gateway through which to boot if the host is not on the same network as the target. If gad has a non-empty value, a routing entry is added indicating that the address is a gateway to the network of the specified boot host.
bootFile		file name The full path name of the file containing the VxWorks run-time image.

To get a file containing the VxWorks run-time image, the boot program needs to know the name of the file containing the run-time image. The boot program also needs to know the identity of the machine that hosts the file. These are provided in the boot parameters: had and fileName. Typically, the boot program gets these parameters from a DHCP or BOOTP message.⁵

To retrieve the image, the boot program uses any of three protocols: TFTP, FTP, or RSH. If the 0x80 bit in the flags parameter is set, the boot program uses TFTP. Otherwise, the boot program uses FTP or RSH to retrieve the image. However, in order to use RSH, the boot program needs a user ID, usr. If the boot program must use FTP, it needs both a user ID and a password, passwd. In addition, if the VxWorks run-time image is resident on a SCSI drive, you can use the other parameter to specify the network interface to which the VxWorks image attaches after it boots.

To support remote file access for startup code in the VxWorks image, you also need to supply a host name, hostName. This parameter is not critical to the boot program. You can leave it empty, if you want. However, entering a meaningful hostName can make messages from the boot program a little easier to read. For detailed descriptions of boot parameters for remote file access, see Table 13-3.

Table 13-3:  Boot Parameters for Remote File Access

Parameter Name from BOOT_PARAMS		Parameter Name from p Command Listing (followed by description)
usr		user (u) The user name to use with FTP or RSH.
passwd		ftp password (pw) The password to use with FTP. If the password is empty, the boot program uses RSH instead of FTP. Supplying a password also has configuration consequences for remote file access and remote login. To access remote files, the target creates a device named according to the value of the hostName parameter. This device is an instance of the netDrv utility. This utility provides remote file access using either RSH or FTP to retrieve the remote file. If you enter a password here, netDrv uses FTP. For more information on netDrv, see 2.10.1 RSH and FTP.
other		other (o) If you are booting from the network, this parameter has no predetermined use. It is optional, and you can leave it empty. However, when booting from a disk (a subject outside the scope of this chapter), bootDev refers to the disk not the network device. If the boot program finds that you have entered a non-empty value for other, the boot program assumes that this value is the name of a network device that you want to attach.

Table 13-4 lists the optional boot parameters. Omitting these parameters from the boot line does not prevent the target from booting.

Table 13-4:  Optional Boot Parameters

Parameter Name from BOOT_PARAMS		Parameter Name from p Command Listing (followed by description)
hostName		host name Can contain the name of the host that supplies the boot file. The startup code in the VxWorks run-time image uses this name for the netDrv device that it creates to handle remote file access, but this name is entirely optional. Leaving it empty breaks nothing, although using a meaningful name here does make the messages from the boot program a little easier to follow. For example, this parameter is used to name the current working directory (if any), which is the netDrv device "hostName:". The target also adds this name (if any) to its host table.
targetName		target name (tn) Contains the name of the target. VxWorks adds this name to its host and route tables.
startupScript		startup script (s) Names the script, if any, to execute in a target shell upon completion of boot.

1:  This boot line address is configurable. The relevant configuration macro is BOOT_LINE_ADRS. If this behavior is inappropriate for your target device, you can copy bootConfig.c, modify the copy, and then use the resulting code as your boot program.

2:  The default boot line is configurable. The relevant configuration macro is DEFAULT_BOOT_LINE.

3:  If the target has NVRAM, and the user specified these parameters in a previous boot session, the boot program knows to save these parameters to an NVRAM boot line for the use of the next boot session.

4:  If you accidentally include both a DHCP and BOOTP client in a boot program, the program uses the DHCP client.

5:  If the target reaches the host through a gateway, the target also needs the gad value, which is included in the same DHCP or BOOTP message that provided the had value.