VxWorks API Reference : OS Libraries
bootpLib - Bootstrap Protocol (BOOTP) client library
bootpLibInit( ) - BOOTP client library initialization
bootpParamsGet( ) - retrieve boot parameters using BOOTP
bootpMsgGet( ) - send a BOOTP request message and retrieve reply
This library implements the client side of the Bootstrap Protocol (BOOTP). This protocol allows a host to initialize automatically by
obtaining its IP address, boot file name, and boot host's IP address over a network. The bootpLibInit( ) routine links this library into the VxWorks image. This happens automatically if INCLUDE_BOOTP is defined at the time the image is built.
When used during boot time, the BOOTP library attempts to retrieve the required configuration information from a BOOTP server using the interface described below. If it is successful, the remainder of the boot process continues as if the information were entered manually.
The bootpParamsGet( ) routine retrieves a set of configuration parameters according to the client-server interaction described in RFC 951 and clarified in RFC 1542. The parameter descriptor structure it accepts as an argument allows the retrieval of any combination of the options described in RFC 1533 (if supported by the BOOTP server and specified in the database). During the default system boot process, 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 bootpMsgGet( ) routine transmits an arbitrary BOOTP request message and provides direct access to any reply. This interface provides a method for supporting alternate BOOTP implementations which may not fully comply with the recommended behavior in RFC 1542. For example, it allows transmission of BOOTP messages to an arbitrary UDP port and provides access to the vendor-specific field to handle custom formats which differ from the RFC 1533 implementation. The bootpParamsGet( ) routine already extracts all options
which that document defines.
The following code fragment demonstrates use of the BOOTP library:
#include "bootpLib.h" #define _MAX_BOOTP_RETRIES 1 struct bootpParams bootParams; struct in_addr clntAddr; struct in_addr hostAddr; char bootFile [SIZE_FILE]; int subnetMask; struct in_addr_list routerList; struct in_addr gateway; struct ifnet * pIf; /* Retrieve the interface descriptor of the transmitting device. */ pIf = ifunit ("ln0"); if (pIf == NULL) { printf ("Device not found.\n"); return (ERROR); } /* Setup buffers for information from BOOTP server. */ bzero ( (char *)&clntAddr, sizeof (struct in_addr)); bzero ( (char *)&hostAddr, sizeof (struct in_addr)); bzero (bootFile, SIZE_FILE); 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.netmask = (struct in_addr *)&subnetMask; routerlist.addr = &gateway; routerlist.num = 1; bootParams.routers = &routerlist; /* @ Send request and wait for reply, retransmitting as necessary up to @ given limit. Copy supplied entries into buffers if reply received. */ result = bootpParamsGet (pIf, _MAX_BOOTP_RETRIES, &clntAddr, &hostAddr, NULL, bootFile, &bootParams); if (result != OK) return (ERROR);
bootpLib.h
RFC 951, RFC 1542, RFC 1533,
bootpLibInit( ) - BOOTP client library initialization
STATUS bootpLibInit ( int maxSize /* largest link-level header, in bytes */ )
This routine creates and initializes the global data structures used by the BOOTP client library to obtain configuration parameters. The maxSize parameter specifies the largest link level header for all supported devices. This value determines the maximum length of the outgoing IP packet containing a BOOTP message.
This routine must be called before using any other library routines. The routine is called automatically if INCLUDE_BOOTP is defined at the time the system is built and uses the BOOTP_MAXSIZE configuration setting for the maxSize parameter.
OK, or ERROR if initialization fails.
S_bootpLib_MEM_ERROR;
bootpParamsGet( ) - retrieve boot parameters using BOOTP
STATUS bootpParamsGet ( struct ifnet * pIf, /* network device used by client */ u_int maxSends, /* maximum transmit attempts */ struct in_addr * pClientAddr, /* retrieved client address buffer */ struct in_addr * pServerAddr, /* buffer for server's IP address */ char * pHostName, /* 64 byte (max) host name buffer */ char * pBootFile, /* 128 byte (max) file name buffer */ struct bootpParams * pBootpParams /* parameters descriptor */ )
This routine performs a BOOTP message exchange according to the process described in RFC 1542, so the server and client UDP ports are always equal to the defined values of 67 and 68.
The pIf argument indicates the network device which will be used to send and receive BOOTP messages. The BOOTP client only supports devices attached to the IP protocol with the MUX/END interface. The MTU size must be large enough to receive an IP packet of 328 bytes (corresponding to the BOOTP message length of 300 bytes). The specified device also must be capable of sending broadcast messages, unless this routine sends the request messages directly to the IP address of a specific server.
The maxSends parameter specifies the total number of requests before before this routine stops waiting for a reply. After the final request, this routine will wait for the current interval before returning error. The timeout interval following each request follows RFC 1542, beginning at 4 seconds and doubling until a maximum limit of 64 seconds.
The pClientAddr parameter provides optional storage for the assigned IP address from the yiaddr field of a BOOTP reply. Since this routine can execute before the system is capable of accepting unicast datagrams or responding to ARP requests for a specific IP address, the corresponding ciaddr field in the BOOTP request message is equal to zero.
The pServerAddr parameter provides optional storage for the IP address of the responding server (from the siaddr field of a BOOTP reply). This routine broadcasts the BOOTP request message unless this buffer is available (i.e. not NULL) and contains the explicit IP address of a BOOTP server as a non-zero value.
The pHostName parameter provides optional storage for the server's host name (from the sname field of a BOOTP reply). This routine also copies any initial string in that buffer into the sname field of the BOOTP request (which restricts booting to a specified host).
The pBootFile parameter provides optional storage for the boot file name (from the file field of a BOOTP reply). This routine also copies any initial string in that buffer into the file field of the BOOTP request message, which typically supplies a generic name to the server.
The remaining fields in the BOOTP request message use the values which RFC 1542 defines. In particular, the giaddr field is set to zero and the suggested "magic cookie" is always inserted in the (otherwise empty) vend field.
The pBootpParams argument provides access to any options defined in RFC 1533 using the following definition:
struct bootpParams { 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 contents of the BOOTP parameter descriptor implicitly selects options for retrieval from the BOOTP server. This routine 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 with this routine 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
bootpMsgGet( ) - send a BOOTP request message and retrieve reply
STATUS bootpMsgGet ( struct ifnet * pIf, /* network device for message exchange */ struct in_addr * pIpDest, /* destination IP address for request */ USHORT srcPort, /* UDP source port for request */ USHORT dstPort, /* UDP destination port for request */ BOOTP_MSG * pBootpMsg, /* request template and reply storage */ u_int maxSends /* maximum number of transmit attempts */ )
This routine sends a BOOTP request using the network interface specified by pIf and waits for any reply. The pIpDest argument specifies the destination IP address. It must be equal to either the broadcast address (255.255.255.255) or the IP address of a specific BOOTP server which is directly reachable using the given network interface. The given interface must support broadcasting in the first case.
The srcPort and dstPort arguments support sending and receiving BOOTP messages with arbitrary UDP ports. To receive replies, any BOOTP server must send those responses to the source port from the request. To comply with the RFC 1542 clarification, the request message must be sent to the reserved BOOTP server port (67) using the reserved BOOTP client port (68).
Except for the UDP port numbers, this routine only sets the bp_xid and bp_secs fields in the outgoing BOOTP message. All other fields in that message use the values from the pBootpMsg argument, which later holds the contents of any BOOTP reply received.
The maxSends parameter specifies the total number of requests to transmit if no reply is received. The retransmission interval starts at 4 seconds and doubles with each attempt up to a maximum of 64 seconds. Any subsequent retransmissions will occur at that maximum interval. To reduce the chances of network flooding, the timeout interval before each retransmission includes a randomized delay of plus or minus one second from the base value. After the final transmission, this routine will wait for the current interval to expire before returning a timeout error.
The target must be able to respond to an ARP request for any IP
address specified in the request template's bp_ciaddr field.
OK, or ERROR.
S_bootpLib_INVALID_ARGUMENT
S_bootpLib_NO_BROADCASTS
S_bootpLib_TIME_OUT