VxWorks Reference Manual : Libraries
bootpLib - BOOTP client library
bootpParamsGet( ) - retrieve boot parameters using BOOTP
bootpMsgSend( ) - send a BOOTP request message
This library implements the client side of the Bootstrap Protocol (BOOTP). This network protocol allows the dynamic configuration of the target's boot parameters at boot time. This is in contrast to using the boot information encoded in system non-volatile RAM or ROM. Thus, at boot time, BOOTP goes over the network to get an IP address, a boot file name, and the boot host's IP address.
The actual transfer of the boot image is handled by a file transfer protocol, such as TFTP or FTP, or by an RSH command.
To access BOOTP services, you can use either the high-level interface supported by bootpParamsGet( ), or the low-level interface supported by bootpMsgSend( ).
The bootpParamsGet( ) routine provides the highest level interface to BOOTP. It accepts a parameter descriptor structure that allows the retrieval of any combination of the options described in RFC 1533 (if supported by the BOOTP server and if specified in the database). During system boot, the routine obtains the boot file, the Internet address, and the host Internet address. It also obtains the subnet mask and the Internet address of an IP router, if available.
The bootpMsgSend( ) routine provides a lower-level interface to BOOTP. It accepts and returns a BOOTP message as a parameter. This interface is more flexible because it gives the caller direct access to the data in the BOOTP request/reply messages. For example, if the BOOTP message includes implementation-specific options not defined in an RFC, the caller can use bootpMsgSend( ) to retrieve them from the vendor-specific field in the BOOTP message. The bootpParamsGet( ) routine already provides all defined options.
The following code provides and example of how to use bootpParamsGet( ):
#include "bootpLib.h" struct bootpParams bootParams; struct in_addr clntAddr; struct in_addr hostAddr; char bootFile [FILENAME_SIZE]; int subnetMask; struct in_addr_list routerList; struct in_addr gateway; char clntAddr [INET_ADDR_LEN]; char bootServer [INET_ADDR_LEN]; char bootFile [SIZE_FILE]; int fileSize; int subnetMask; char gateway [INET_ADDR_LEN]; bzero ( (char *)&clntAddr, sizeof (struct in_addr)); bzero ( (char *)&hostAddr, sizeof (struct in_addr)); bzero (bootFile, FILENAME_SIZE); subnetMask = 0; bzero ( (char *)&gateway, sizeof (struct in_addr)); /* Set all pointers in parameter descriptor to NULL. */ bzero ((char *)&bootParams, sizeof (struct bootpParams)); /* Set pointers corresponding to desired options. */ bootParams.clientAddr = &clntAddr; bootParams.bootHostAddr = &hostAddr; bootParams.bootfile = pBootFile; bootParams.netmask = (struct in_addr *)&subnetMask; routerlist.addr = &gateway; routerlist.num = 1; bootParams.routers = &routerlist; if (bootpParamsGet ("ln0", 0, 0, &bootParams) == ERROR) return (ERROR);
Certain targets (typically those with no NVRAM) construct their Ethernet address based on the target's IP address. An IP address must be entered for these targets in order to boot over the network. The remaining information can be obtained with BOOTP.
BOOTP is not supported over the following network interfaces: if_sl (SLIP) and if_ie (Sun IE driver). if_sl (SLIP) and if_ppp (PPP).
bootpLib.h
bootLib, RFC 951, RFC 1542, RFC 1533, VxWorks Programmer's Guide: Network
bootpParamsGet( ) - retrieve boot parameters using BOOTP
STATUS bootpParamsGet ( char * ifName, /* network interface name */ int port, /* optional port number */ u_int timeOut, /* timeout in ticks */ struct bootpParams * pBootpParams /* parameters descriptor */ )
This routine transmits a BOOTP request message over the network interface associated with ifName. This interface must already be attached and initialized prior to calling this routine.
A non-zero value for port specifies an alternate BOOTP server port. A zero value means the default BOOTP server port (67).
timeOut specifies a timeout value in ticks. If no reply is received within this period, an error is returned. Specify zero for an infinite timeout value.
pBootpParams is a structure pointer to a bootpParams structure that you can use to indicate the parameters of interest to you. The bootpParams structure is defined as follows:
struct bootpParams { struct in_addr * clientAddr; struct in_addr * bootHostAddr; char * bootfile; char * serverName; struct in_addr * netmask; unsigned short * timeOffset; struct in_addr_list * routers; struct in_addr_list * timeServers; struct in_addr_list * nameServers; struct in_addr_list * dnsServers; struct in_addr_list * logServers; struct in_addr_list * cookieServers; struct in_addr_list * lprServers; struct in_addr_list * impressServers; struct in_addr_list * rlpServers; char * clientName; unsigned short * filesize; char * dumpfile; char * domainName; struct in_addr * swapServer; char * rootPath; char * extoptPath; unsigned char * ipForward; unsigned char * nonlocalSourceRoute; struct in_addr_list * policyFilter; unsigned short * maxDgramSize; unsigned char * ipTTL; unsigned long * mtuTimeout; struct ushort_list * mtuTable; unsigned short * intfaceMTU; unsigned char * allSubnetsLocal; struct in_addr * broadcastAddr; unsigned char * maskDiscover; unsigned char * maskSupplier; unsigned char * routerDiscover; struct in_addr * routerDiscAddr; struct in_addr_list * staticRoutes; unsigned char * arpTrailers; unsigned long * arpTimeout; unsigned char * etherPacketType; unsigned char * tcpTTL; unsigned long * tcpInterval; unsigned char * tcpGarbage; char * nisDomain; struct in_addr_list * nisServers; struct in_addr_list * ntpServers; char * vendString; struct in_addr_list * nbnServers; struct in_addr_list * nbddServers; unsigned char * nbNodeType; char * nbScope; struct in_addr_list * xFontServers; struct in_addr_list * xDisplayManagers; char * nispDomain; struct in_addr_list * nispServers; struct in_addr_list * ipAgents; struct in_addr_list * smtpServers; struct in_addr_list * pop3Servers; struct in_addr_list * nntpServers; struct in_addr_list * wwwServers; struct in_addr_list * fingerServers; struct in_addr_list * ircServers; struct in_addr_list * stServers; struct in_addr_list * stdaServers; };This structure allows the retrieval of any BOOTP option specified in RFC 1533. The list of 2-byte (unsigned short) values is defined as:
struct ushort_list { unsigned char num; unsigned short * shortlist; };The IP address lists use the following similar definition:
struct in_addr_list { unsigned char num; struct in_addr * addrlist; };When these lists are present, the routine stores values retrieved from the BOOTP reply in the location indicated by the shortlist or addrlist members. The amount of space available is indicated by the num member. When the routine returns, the num member indicates the actual number of entries retrieved. In the case of bootpParams.policyFilter.num and bootpParams.staticRoutes.num, the num member value should be interpreted as the number of IP address pairs requested and received.The following members of the bootpParams structure are also used for both input and output:
- clientAddr
- Contains a pointer that holds the client's Internet address. On input, if it contains a non-NULL value, it is interpreted as a pointer to an Internet address of type struct in_addr and passed on to the BOOTP server in the bp_ciaddr member of the BOOTP message structure (BOOTP_MSG). The server will use it as a lookup field into the BOOTP database. When a reply is received, the client's assigned Internet address is copied to the clientAddr member.
- bootHostAddr
- Contains a pointer that holds the host's IP address. On input, if it contains a non-NULL value, it is interpreted as the host where the BOOTP message is to be sent. Note that this host must be local to the pIf network. If NULL, the BOOTP message is sent to the local broadcast address. On return, the host's IP address is copied to the bootHostAddr member.
On input, if the bootpParams.bootfile member points to a non-empty string, the contents are passed to the BOOTP server in the bp_file member of the BOOTP message structure (BOOTP_MSG). When a reply is received, the file name retrieved from the BOOTP server is copied to the bootpParams.bootfile member as a NULL-terminated string.
The remaining elements in the BOOTP parameters descriptor are used to select options for retrieval from the BOOTP server. The BOOTP library attempts to retrieve the values for any options whose corresponding field pointers are non-NULL values. To obtain these parameters, the BOOTP server must support the vendor-specific options described in RFC 1048 (or its successors) and the corresponding parameters must be specified in the BOOTP server database. Where meaningful, the values are returned in host byte order.
The BOOTP request issued during system startup attempts to retrieve a subnet mask for the boot device, in addition to the host and client addresses, and the boot file name.
OK, or ERROR if unsuccessful.
bootpLib, bootLib, RFC 1048, RFC 1533
bootpMsgSend( ) - send a BOOTP request message
STATUS bootpMsgSend ( char * ifName, /* network interface name */ struct in_addr * pIpDest, /* destination IP address */ int port, /* port number */ BOOTP_MSG * pBootpMsg, /* pointer to BOOTP message */ u_int timeOut /* timeout in ticks */ )
This routine sends the BOOTP message indicated by pBootpMsg using the network interface specified by ifName. The pIpDest argument specifies the destination IP address. In most cases, the broadcast address (255.255.255.255) is used. However, this parameter also accepts the IP address of a particular BOOTP server. That server must reside on the same subnet as the specified network interface.
A non-zero value for port specifies an alternate BOOTP server port. Otherwise, the default port (67) is used.
This routine always sets the values of the bp_op, bp_xid, and bp_secs members in the BOOTP message structure, but it allows the caller to assign values to any of the other members. However, if the bp_hlen member is 0, the routine uses the Ethernet address of the specified network interface for the bp_chaddr member and sets bp_type to 1 and bp_hlen to 6 as required for that address.
The bootpMsgSend( ) routine will retransmit the BOOTP message if it gets no reply. The retransmission time increases exponentially but is bounded by the number of ticks specified in the timeOut parameter. If no reply is received within this period, an error is returned. A value of zero specifies an infinite timeout value.
If bp_ciaddr is specified, the BOOTP server may assume that the client will respond to an ARP request.
OK, or ERROR.
S_bootpLib_INVALID_ARGUMENT
S_bootpLib_NO_BROADCASTS
S_bootpLib_TIME_OUT