VxWorks Reference Manual : Libraries
dhcpcBootLib - DHCP boot-time client library
dhcpcBootInit( ) - set up the DHCP client parameters and data structures
dhcpcBootBind( ) - initialize the network with DHCP at boot time
dhcpcBootInformGet( ) - obtain additional configuration parameters with DHCP
This library contains the interface for the client side of the Dynamic Host Configuration Protocol (DHCP) used during system boot. DHCP is an extension of BOOTP, the bootstrap protocol. Like BOOTP, the protocol allows automatic system startup by providing an IP address, boot file name, and boot host's IP address over a network. Additionally, DHCP provides the complete set of configuration parameters defined in the Host Requirements RFCs and allows automatic reuse of network addresses by specifying a lease duration for a set of configuration parameters. This library is linked into the boot ROM image automatically if INCLUDE_DHCPC is defined at the time that image is constructed.
The VxWorks boot program uses this library to obtain configuration parameters with DHCP according to the client-server interaction detailed in RFC 2131 using the boot device specified in the boot parameters. The DHCP client supports devices attached to the IP protocol with the MUX/END interface. It also supports BSD Ethernet devices attached to the IP protocol.
To use DHCP, first build a boot ROM image with INCLUDE_DHCPC defined and set
the appropriate flag in the boot parameters before initiating booting with the "@" command. The DHCP client will attempt to retrieve entries for the boot file name, and host IP address, as well as a subnet mask and broadcast address for the boot device. If a target IP address is not available, the client will retrieve those parameters in the context of a lease. Otherwise, it will search for permanent assignments using a simpler message exchange. Any entries retrieved with either method will only be used if the corresponding fields in the boot parameters are blank.
After DHCP retrieves the boot parameters, the specified boot file is loaded and the system restarts. As a result, the boot-time DHCP client cannot renew any lease which may be associated with the assigned IP address. To avoid potential IP address conflicts while loading the boot file, the DHCPC_MIN_LEASE value should be set to exceed the file transfer time. In addition, the boot file must also contain the DHCP client library so that the lease obtained before the restart can be renewed. Otherwise, the network initialization using the boot parameters will fail. These restrictions do not apply if the target IP address is entered manually since the boot parameters do not involve a lease in that case.
dhcpcBootLib.h
dhcpcBootLib, dhcpcLib, RFC 1541, RFC 1533
dhcpcBootInit( ) - set up the DHCP client parameters and data structures
void * dhcpcBootInit ( struct ifnet * pIf, /* network device used by client */ int serverPort, /* port used by DHCP servers (default 67) */ int clientPort, /* port used by DHCP clients (default 68) */ int maxSize, /* largest DHCP message supported, in bytes */ int offerTimeout, /* interval to get additional DHCP offers */ int defaultLease, /* default value for requested lease length */ int minLease /* minimum accepted lease length */ )
This routine creates any necessary data structures and sets the client's option request list to retrieve a subnet mask and broadcast address for the network interface indicated by pIf. The routine is executed automatically by the boot program when INCLUDE_DHCPC is defined and the automatic configuration option is set in the boot flags. The network interface specified by pIf is used to transmit and receive all DHCP messages during the lease negotiation. The DHCP client supports interfaces attached to the IP protocol using the MUX/END interface and BSD Ethernet devices attached to that protocol. The interface must be capable of sending broadcast messages. The maxSize parameter specifies the maximum length supported for any DHCP message, including the UDP and IP headers and the link level header. The maximum length of the DHCP options field is based on this value or the MTU size for the given interface, whichever is less. The smallest valid value for the maxSize parameter is 576 bytes, corresponding to the minimum IP datagram a host must accept. The MTU size of the network interface must be large enough to handle those datagrams.
N/A
Lease handle for later use, or NULL if lease startup fails.
dhcpcBootBind( ) - initialize the network with DHCP at boot time
STATUS dhcpcBootBind (void)
This routine performs the client side of a DHCP negotiation according to RFC 2131. The negotiation uses the network device specified with the initialization call. The addressing information retrieved is applied to that network device. Because the boot image is replaced by the downloaded target image, the resulting lease cannot be renewed. Therefore, the minimum lease length specified by DHCPC_MIN_LEASE must be set so that the target image has sufficient time to download and begin monitoring the lease. This routine is called automatically by the boot program when INCLUDE_DHCPC is defined and the automatic configuration option is set in the boot flags and no target address is present.
OK if negotiation is successful, or ERROR otherwise.
N/A
dhcpcBootInformGet( ) - obtain additional configuration parameters with DHCP
STATUS dhcpcBootInformGet ( char * pAddrString /* known address assigned to client */ )
This routine uses DHCP to retrieve additional configuration parameters for a client with the externally configured network address given by the pAddrString parameter. It sends an INFORM message and waits for a reply following the process described in RFC 2131. The message exchange uses the network device specified with the initialization call. Any interface information retrieved is applied to that network device. Since this process does not establish a lease, the target address will not contain any timestamp information so that the runtime image will not attempt to verify the configuration parameters. This routine is called automatically by the boot program when INCLUDE_DHCPC is defined and the automatic configuration option is set in the boot flags if a target address is already present.
OK if negotiation is successful, or ERROR otherwise.
N/A