bootLib

NAME

bootLib - boot ROM subroutine library

ROUTINES

bootStringToStruct( ) - interpret the boot parameters from the boot line
bootStructToString( ) - construct a boot line
bootParamsShow( ) - display boot line parameters
bootParamsPrompt( ) - prompt for boot line parameters
bootLeaseExtract( ) - extract the lease information from an Internet address
bootNetmaskExtract( ) - extract the net mask field from an Internet address
bootBpAnchorExtract( ) - extract a backplane address from a device field

DESCRIPTION

This library contains routines for manipulating a boot line. Routines are provided to interpret, construct, print, and prompt for a boot line.
When VxWorks is first booted, certain parameters can be specified, such as network addresses, boot device, host, and start-up file. This information is encoded into a single ASCII string known as the boot line. The boot line is placed at a known address (specified in config.h) by the boot ROMs so that the system being booted can discover the parameters that were used to boot the system. The boot line is the only means of communication from the boot ROMs to the booted system.
The boot line is of the form:
bootdev(unitnum,procnum)hostname:filename e=# b=# h=# g=# u=userid pw=passwd f=#
tn=targetname s=startupscript o=other
where:

bootdev
the boot device (required); for example, "ex" for Excelan Ethernet, "bp" for backplane. For the backplane, this field can have an optional anchor address specification of the form "bp=adrs" (see bootBpAnchorExtract( )).

unitnum
the unit number of the boot device (0..n).

procnum
the processor number on the backplane, 0..n (required for VME boards).

hostname
the name of the boot host (required).

filename
the file to be booted (required).

e
the Internet address of the Ethernet interface. This field can have an optional subnet mask of the form inet_adrs:subnet_mask. If DHCP is used to obtain the configuration parameters, lease timing information may also be present. This information takes the form lease_duration:lease_origin and is appended to the end of the field. (see bootNetmaskExtract( ) and bootLeaseExtract( )).

b
the Internet address of the backplane interface. This field can have an optional subnet mask and/or lease timing information as "e".

h
the Internet address of the boot host.

g
the Internet address of the gateway to the boot host. Leave this parameter blank if the host is on same network.

u
a valid user name on the boot host.

pw
the password for the user on the host. This parameter is usually left blank. If specified, FTP is used for file transfers.

f
the system-dependent configuration flags. This parameter contains an or of option bits defined in sysLib.h.

tn
the name of the system being booted

s
the name of a file to be executed as a start-up script.

o
"other" string for use by the application.

The Internet addresses are specified in "dot" notation (e.g., 90.0.0.2). The order of assigned values is arbitrary.

EXAMPLE

enp(0,0)host:/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=bob pw=realtime f=2 tn=target
 s=host:/usr/bob/startup o=any_string

INCLUDE FILES

bootLib.h

bootStringToStruct( )

NAME

bootStringToStruct( ) - interpret the boot parameters from the boot line

SYNOPSIS

char *bootStringToStruct
    (
    char *        bootString, /* boot line to be parsed */
    BOOT_PARAMS * pBootParams /* where to return parsed boot line */
    )

DESCRIPTION

This routine parses the ASCII string and returns the values into the provided parameters.
For a description of the format of the boot line, see the manual entry for bootLib

RETURNS

A pointer to the last character successfully parsed plus one (points to EOS, if OK). The entire boot line is parsed.

bootStructToString( )

NAME

bootStructToString( ) - construct a boot line

SYNOPSIS

STATUS bootStructToString
    (
    char *        paramString, /* where to return the encoded boot line */
    BOOT_PARAMS * pBootParams  /* boot line structure to be encoded */
    )

DESCRIPTION

This routine encodes a boot line using the specified boot parameters.
For a description of the format of the boot line, see the manual entry for bootLib.

RETURNS

OK.

bootParamsShow( )

NAME

bootParamsShow( ) - display boot line parameters

SYNOPSIS

void bootParamsShow
    (
    char * paramString /* boot parameter string */
    )

DESCRIPTION

This routine displays the boot parameters in the specified boot string one parameter per line.

RETURNS

N/A

bootParamsPrompt( )

NAME

bootParamsPrompt( ) - prompt for boot line parameters

SYNOPSIS

void bootParamsPrompt
    (
    char * string /* default boot line */
    )

DESCRIPTION

This routine displays the current value of each boot parameter and prompts the user for a new value. Typing a RETURN leaves the parameter unchanged. Typing a period (.) clears the parameter.
The parameter string holds the initial values. The new boot line is copied over string. If there are no initial values, string is empty on entry.

RETURNS

N/A

bootLeaseExtract( )

NAME

bootLeaseExtract( ) - extract the lease information from an Internet address

SYNOPSIS

int bootLeaseExtract
    (
    char *   string,     /* string containing addr field */
    u_long * pLeaseLen,  /* pointer to storage for lease duration */
    u_long * pLeaseStart /* pointer to storage for lease origin */
    )

DESCRIPTION

This routine extracts the optional lease duration and lease origin fields from an Internet address field for use with DHCP. The lease duration can be specified by appending a colon and the lease duration to the netmask field. For example, the "inet on ethernet" field of the boot parameters could be specified as:
    inet on ethernet: 90.1.0.1:ffff0000:1000
If no netmask is specified, the contents of the field could be:
    inet on ethernet: 90.1.0.1::ffffffff
In the first case, the lease duration for the address is 1000 seconds. The second case indicates an infinite lease, and does not specify a netmask for the address. At the beginning of the boot process, the value of the lease duration field is used to specify the requested lease duration. If the field not included, the value of DHCP_DEFAULT_LEASE is used instead.
The lease origin is specified with the same format as the lease duration, but is added during the boot process. The presence of the lease origin field distinguishes addresses assigned by a DHCP server from addresses entered manually. Addresses assigned by a DHCP server may be replaced if the bootstrap loader uses DHCP to obtain configuration parameters. The value of the lease origin field at the beginning of the boot process is ignored.
This routine extracts the optional lease duration by replacing the preceding colon in the specified string with an EOS and then scanning the remainder as a number. The lease duration and lease origin values are returned via the pLeaseLen and pLeaseStart pointers, if those parameters are not NULL.

RETURNS

  2 if both lease values are specified correctly in string, or
-2 if one of the two values is specified incorrectly. If only the lease duration is found, it returns:
  1 if the lease duration in string is specified correctly,
  0 if the lease duration is not specified in string, or
-1 if an invalid lease duration is specified in string.

bootNetmaskExtract( )

NAME

bootNetmaskExtract( ) - extract the net mask field from an Internet address

SYNOPSIS

STATUS bootNetmaskExtract
    (
    char * string,  /* string containing addr field */
    int *  pNetmask /* pointer where to return net mask */
    )

DESCRIPTION

This routine extracts the optional subnet mask field from an Internet address field. Subnet masks can be specified for an Internet interface by appending to the Internet address a colon and the net mask in hexadecimal. For example, the "inet on ethernet" field of the boot parameters could be specified as:
    inet on ethernet: 90.1.0.1:ffff0000
In this case, the network portion of the address (normally just 90) is extended by the subnet mask (to 90.1). This routine extracts the optional trailing subnet mask by replacing the colon in the specified string with an EOS and then scanning the remainder as a hex number. This number, the net mask, is returned via the pNetmask pointer.
This routine also handles an empty netmask field used as a placeholder for the lease duration field (see bootLeaseExtract( ) ). In that case, the colon separator is replaced with an EOS and the value of netmask is set to 0.

RETURNS

1 if the subnet mask in string is specified correctly,
0 if the subnet mask in string is not specified, or
-1 if an invalid subnet mask is specified in string.

bootBpAnchorExtract( )

NAME

bootBpAnchorExtract( ) - extract a backplane address from a device field

SYNOPSIS

STATUS bootBpAnchorExtract
    (
    char * string,      /* string containing adrs field */
    char * *pAnchorAdrs /* pointer where to return anchor address */
    )

DESCRIPTION

This routine extracts the optional backplane anchor address field from a boot device field. The anchor can be specified for the backplane driver by appending to the device name (i.e., "bp") an equal sign (=) and the address in hexadecimal. For example, the "boot device" field of the boot parameters could be specified as:
    boot device: bp=800000
In this case, the backplane anchor address would be at address 0x800000, instead of the default specified in config.h.
This routine picks off the optional trailing anchor address by replacing the equal sign (=) in the specified string with an EOS and then scanning the remainder as a hex number. This number, the anchor address, is returned via the pAnchorAdrs pointer.

RETURNS

1 if the anchor address in string is specified correctly,
0 if the anchor address in string is not specified, or
-1 if an invalid anchor address is specified in string.

bootLib

NAME

ROUTINES

DESCRIPTION

EXAMPLE

INCLUDE FILES

SEE ALSO

bootStringToStruct( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bootStructToString( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bootParamsShow( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bootParamsPrompt( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bootLeaseExtract( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bootNetmaskExtract( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

bootBpAnchorExtract( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO