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
dhcpcBootOptionSet( ) - add an option to the option request list
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 1541 using the boot device specified in the boot parameters. The boot device must be capable of sending broadcast messages. Currently, only Ethernet devices and the shared-memory network drivers are supported. 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, host IP address, and target IP address, as well as a subnet mask and broadcast address for the boot device. Any entries retrieved 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 the lease 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.
dhcpcBootLib.h
dhcpcBootLib, dhcpcLib, RFC 1541, RFC 1533
dhcpcBootInit( ) - set up the DHCP client parameters and data structures
STATUS dhcpcBootInit ( struct ifnet * pIf /* network device used by client */ )
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. That interface must be capable of sending broadcast messages. Currently, only Ethernet devices and the shared-memory network drivers are supported.
N/A
OK, or ERROR if could not initialize.
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 1541. 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.
OK if negotiation is successful, or ERROR otherwise.
N/A
dhcpcBootOptionSet( ) - add an option to the option request list
STATUS dhcpcBootOptionSet ( int option, /* RFC 1533 tag of desired option */ long value, /* numeric value for option */ long length, /* length of data (if any) or 0 if unused */ char * pData /* option data, or NULL if none */ )
This routine sets most client-to-server transmission options for a lease established by the boot program. The option parameter specifies an option tag as defined in RFC 1533 and the updates published in the Internet Draft of November 1996. The boot program automatically sets all necessary options for target configuration. This routine is only provided to support special circumstances in which additional options are necessary. Any options requested with this routine may be retrieved after the runtime image has started. For a listing of defined aliases for the known option tags, see dhcp/dhcp.h. This routine cannot set the options associated with the following tags:
_DHCP_PAD_TAG
_DHCP_OPT_OVERLOAD_TAG
_DHCP_MSGTYPE_TAG
_DHCP_SERVER_ID_TAG
_DHCP_REQ_LIST_TAG
_DHCP_MAXMSGSIZE_TAG
_DHCP_END_TAGMost options only require specification of the appropriate tag in the option parameter. In those cases, the dhcpcBootOptionSet( ) call adds the specified option tag to the option request list, if possible. However, some options require additional information. The tags for these options are:
_DHCP_VENDOR_SPEC_TAG
_DHCP_REQUEST_IPADDR_TAG
_DHCP_LEASE_TIME_TAG
_DHCP_ERR_MSG_TAG
_DHCP_CLASS_ID_TAG
_DHCP_CLIENT_ID_TAGThe _DHCP_LEASE_TIME_TAG and _DHCP_CLIENT_ID_TAG options each require a value parameter. For _DHCP_LEASE_TIME_TAG, value specifies the desired lease length. For _DHCP_CLIENT_ID_TAG, value specifies the type for a type/value pair. No other options use this parameter.
The _DHCP_VENDOR_SPEC_TAG, _DHCP_CLASS_ID_TAG and _DHCP_CLIENT_ID_TAG tags each require a value for the length parameter to specify the number of bytes of data provided. No other options use this parameter.
Use the data parameter with the following option tags:
- _DHCP_VENDOR_SPEC_TAG
- The data parameter points to a list of "length" bytes of options in the format specified by RFC 1533.
- _DHCP_REQUEST_IPADDR_TAG
- The data parameter points to the string representation of the desired Internet address for the client.
- _DHCP_ERRMSG_TAG
- The data parameter points to the error message to send to the server when releasing the current IP address.
- _DHCP_CLASS_ID_TAG
- The data parameter points to length bytes used as the value for the vendor class identifier.
- _DHCP_CLIENT_ID_TAG
- The data parameter points to length bytes used as the value of a type/value pair.
- -
- The data parameter should be NULL for all other options.
With the exception of the _DHCP_ERR_MSG_TAG option, the DHCP specification forbids changing options after a lease has been established. Therefore, this routine should not be used after the dhcpcBootBind( ) call. Changing any option other than the error message at that point could have unpredictable results.
OK if option set successfully, or ERROR if option is invalid or storage failed.
N/A