Renesas NetX DHCP Application Note
Application Note
Renesas Synergy™ Platform
NetX™ DHCP Client Module Guide
Introduction
This module guide will enable you to effectively use a module in your own design. Upon completion of this
guide, you will be able to add this module to your own design, configure it correctly for the target application
and write code, using the included application project code as a reference and efficient starting point.
References to more detailed API descriptions and suggestions of other application projects that demonstrate
more advanced uses of the module are av ailab le in the Renesas Syner gy™ Knowledge Base (as described
in the References Section at the end of this document) and should be valuable resources for creating more
complex designs.
The Dynamic Host Configuration Protocol (DHCP) is an extremely useful protocol to obtain an IP address
and network parameters. The DHCP is designed to extend the basic functionality of the BOOTP (which is
limited to static address configuration) to include a completely dynamic IP address allocation through leasing
an IP address to a client for a specified period of time. The DHCP can also be configured to allocate IP
addresses in a static manner, like the BOOTP. An application’s IP address is one of the supplied parameters
for the NetX
application, either statically or through the user configuration. When the application does not know or care
what its IP address is, the NetX is initialized with a zero IP address ; a DHCP client component added to NetX
can then obtain an IP address.
™
component. Supplying the IP address poses no problem if the IP address is known to the
This document provides an overview of the key elements related to the NetX DHCP Client module
implementation on the Renesas Synergy Platform. This document’s primary focus is on the addition and
configuration of the NetX DHCP Client module to a Renesas Synergy Platform project. For details on the
operation of this module, consult the document, NetX™ Dynamic Host Configuration Protocol for Clients
User’s Guide for the Renesas Synergy™ Platform. It is part of X-Ware™ Component Documents for
Renesas Synergy™ zip file available from the Synergy Gallery (https://www.renesas.com/synergy/software).
Contents
1. NetX DHCP Client Module Features ........................................................................................ 2
2. NetX DHCP Client Module APIs Over view ............................................................................... 2
3. NetX DHCP Client Module Operational Overview .................................................................... 4
3.1 NetX DHCP Client Module Important Operational Notes and Limitations .............................................. 5
4. Including the NetX DHCP Client Module in an Application ....................................................... 6
5. Configuring the NetX DHCP Client Module .............................................................................. 7
5.1 Configuration Settings for the NetX DHCP Client Lower-Level Modules ................................................ 8
5.2 NetX DHCP Client Module Clock Configuration .................................................................................... 11
5.3 NetX DHCP Client Module Pin Configuration ....................................................................................... 11
6. Using the NetX DHCP Client Module in an Application .......................................................... 11
7. The NetX DHCP Client Module Application Project................................................................ 12
8. Customizing the NetX DHCP Client Module for a Target Application ..................................... 15
9. Running the NetX DHCP Client Module Application Project ................................................... 16
10. NetX DHCP Client Module Conclus io n .................................................................................. 18
11. NetX DHCP Client Module Next St ep s................................................................................... 18
12. Reference Information ........................................................................................................... 19
R11AN0138EU0103 Rev.1.03 Page 1 of 21
May.02.19
Renesas Synergy™ Platform NetX™ DHCP Client Module Guid e
Function Name
Example API Call and Description
nx_dhcp_create
nx_dhcp_create(&my_dhcp, &my_ip, "My DHCP");
nx_dhcp_clear_broadcast_flag
nx_dhcp_clear_broadcast_flag(&my_dhcp,
Clear broadcast flag on Client messages.
1. NetX DHCP Client Module Features
• The NetX DHCP Client module is compliant with RFC2132, RFC2131, and related RFCs.
• The module provides high-level APIs to:
Create and delete a DHCP client instance
Start, stop, and reinitialize the DHCP client (to restart the DHCP client protocol)
Request a specific IP Address from the server
Specify the network interfac e to run the DHCP client o n
Supply an application-created packet pool to the DHCP client
Figure 1. NetX DHCP Client Module Block Diagram
2. NetX DHCP Client Module APIs Overview
The NetX DHCP Client module defines APIs for creating and starting the DHCP client. Internally, the DHCP
client handles all communication with the DHCP server to obtain an IP address. The following table lists the
complete set of module APIs with an example API call and a brief description of each. A status return values
table follows the API summary table.
Table 1. NetX DHCP Client Module API Summary
Create a DHCP instance.
NX_TRUE);
R11AN0138EU0103 Rev.1.03 Page 2 of 21
May.02.19
Renesas Synergy™ Platform NetX™ DHCP Client Module Guid e
Function Name
Example API Call and Description
nx_dhcp_delete
nx_dhcp_delete(&my_dhcp);
nx_dhcp_decline
nx_dhcp_decline(&my_dhcp);
Send Decline message to server.
nx_dhcp_force_renew
nx_dhcp_force_renew(&my_dhcp);
Handle Server force renew message.
nx_dhcp_packet_pool_set
nx_packet_pool_create(&dhcp_pool, "DHCP Client
creates its own packet pool.
nx_dhcp_release
nx_dhcp_release(&my_dhcp);
Send Release message to server.
nx_dhcp_reinitialize
nx_dhcp_reinitialize(&my_dhcp);
and gateway registered with the IP instance.
nx_dhcp_request_client_ip
nx_dhcp_request_client_ip(&my_dhcp,
Request a specific IP address.
nx_dhcp_send_request
nx_dhcp_send_request(&my_dhcp,
allowed).
nx_dhcp_server_address_get
nx_dhcp_server_address_get(&dhcp_0,
Retrieve DHCP Client’s DHCP server address.
nx_dhcp_set_interface_index
nx_dhcp_set_interface_index(&my_dhcp, 1);
Specify the network interface to run DHCP Client.
nx_dhcp_start
nx_dhcp_start(&my_dhcp);
Start DHCP processing.
nx_dhcp_state_change_notify
nx_dhcp_state_change_notify(&my_dhcp,
Notify application of DHCP state change.
nx_dhcp_stop
nx_dhcp_stop(&my_dhcp);
Stop DHCP processing.
nx_dhcp_user_option_retrieve
nx_dhcp_user_option_retrieve(&my_dhcp,
Retrieve the specified DHCP option.
nx_dhcp_user_option_convert
nx_dhcp_user_option_convert(dns_ip_string);
Convert four bytes to ULONG.
The following services require that Persistent client state be enabled
nx_dhcp_suspend
nx_dhcp_suspend(&g_dhcp_client0);
Suspend the DHCP Client thread.
Delete a DHCP instance.
Packet Pool",
NX_DHCP_PACKET_PAYLOAD, pointer, (15 *
NX_DHCP_PACKET_PAYLOAD));
nx_dhcp_create(&dhcp_0, &ip_0, "janetsdhcp1");
nx_dhcp_packet_pool_set(&my_dhcp,
packet_pool_ptr);
Set the DHCP Client packet pool. By default, the DHCP Client
Clear DHCP client network parameters and clear IP address
IP(192,168,0,6), NX_TRUE);
NX_DHCP_TYPE_INFORMREQUEST);
Send DHCP message to server (only INFORM_REQUEST is
&server_address);
my_state_change);
NX_DHCP_OPTION_DNS_SVR,
dns_ip_string, &size);
R11AN0138EU0103 Rev.1.03 Page 3 of 21
May.02.19
Renesas Synergy™ Platform NetX™ DHCP Client Module Guid e
Function Name
Example API Call and Description
nx_dhcp_resume
nx_dhcp_resume (&g_dhcp_client0);
Resume the DHCP Client thread.
nx_dhcp_client_update_time_remaining
nx_dhcp_client_update_time_remaining(*g_dhcp_c
nx_dhcp_client_create_record
nx_dhcp_client_create_record(&g_dhcp_client0)
Client based on Client lease data.
nx_dhcp_client_restore_record
nx_dhcp_client_restore_record(&g_dhcp_client,
time remaining on its lease.
Name
Description
NX_SUCCESS
Successful API call.
NX_PTR_ERROR*
Invalid pointer input.
NX_THREADS_ONLY_CALLER_CHECKING*
Invalid caller of this service.
NX_INVALID_INTERFACE
NetX is not enabled on the input interface
NX_NOT_ENABLED
Not enabled to set the DHCP Client packet pool.
NX_DHCP_NOT_STARTED
DHCP Client not started.
NX_DHCP_NOT_BOUND
The IP address has not been leased so the current
operation is not allowed.
NX_DHCP_INVALID_MESSAGE
Illegal message type to send.
NX_DHCP_BAD_INTERFACE_INDEX*
An invalid network interface supplied
NX_DHCP_UNKNOWN_OPTION
Unknown DHCP option to extract from DHCP server
response
NX_DHCP_INVALID_IP_REQUEST*
Invalid address for the DHCP Client to request
NX_DHCP_INVALID_PAYLOAD
Packet pool for the DHCP Client has insufficient payload
NX_DHCP_ALREADY_STARTED
DHCP Client thread task has already started
NX_DHCP_PARSE_ERROR
Unable to parse requested option from Server response
NX_DHCP_DEST_TO_SMALL
Supplied buffer too small to hold the requested option
data for user requesting option data
lient0, 1000)
This updates the time remaining on the IP lease by the input
time in timer ticks, such as the time interval while the DHCP
Client thread was suspended.
This fills in a client record structure associated with the DHCP
client_record_ptr, time_elapsed)
The Client record points to data to restore to the DHCP Client
itself, and time elapsed is subtracted from the DHCP Client
Note: For details on operation and definitions for the function data structures, typedefs, defines, API data,
API structures and function variables review the associated Express Logic User’s Manual accessible
as described in the Reference section later in this document.
Table 2. Status Return Values
Note: Lower-level drivers may return common error codes. Refer to the SSP User’s Man u al API
References for the associated module for a definition of all relevant status return values.
*These error codes are returned on ly if error checking is enabled. For details on error checking
services in NetX, refer to the NetX User Guide for the Renesas S yner gy™ Platform.
3. NetX DHCP Client Module Operational Over view
The DHCP Client module handles all the details in obtaining an IP address, registering it with the IP instance,
and renewing the IP address lease before the lease expires.
A NetX IP instance is created; it has a zero IP address and is enabled for User Datagram Protocol (UDP)
and the Address Resolution Protocol (ARP), respectively. The Reverse ARP (RARP) s hou ld not be ena bl ed;
a DHCP Client is then created. Its creation creates an UDP socket for sending and receiving DHCP
messages. By default, the DHCP Client creates its own packet pool based on the settings Minimum packet
payload size and Number of packets in packet pool (see the following table). The Minimum Client
R11AN0138EU0103 Rev.1.03 Page 4 of 21
May.02.19
Renesas Synergy™ Platform NetX™ DHCP Client Module Guid e
packet payload size must be large enough to include DHCP data, IP, UDP headers, and the physical frame
header.
• For Ethernet networks, this minimum payload is 592 bytes, which is the default setting of Minimum
Client packet payload size.
• For other network types (such as Wi-Fi), the frame-header size is larger, and minimum size must be
increased correspondingly.
When the packet pool is created, the DHCP Client verifies that the packet payload is not less than the
minimum required payload size.
The DHCP Client can request a specific IP address using the nx_dhcp_request_client_ip service and
supply a non-zero IP address before starting the DHCP Client. Normally, the request is useful for a device
previously assigned an IP address that wishes to keep the same IP address. Note the server is not obligated
to accommodate this request.
When the DHCP Client is started, it binds the socket to a DHCP port (by default 68) and begins sending and
receiving packets through that socket. When the client is assigned an IP address, it automatically registers
the IP address with NetX. The server supplies the network mask and network gateway, and the DHCP Client
module updates NetX with that information.
When the server assigns the Client an IP address, it may also supply other network information, such as the
DNS server and the NTP server. The application can obtain those values using the
nx_dhcp_user_option_retrieve service.
The DHCP Client keeps track of the time remaining on the IP lease. It automatically sends Renew requests
to the DHCP Server when time to renew. If the server is no longer on the network, or is otherwise not
responding, the client sends broadcast requests to any DHCP Server on the network. If the lease expires
without a renewal or rebinding, the client is returned to the NX_DHCP_STATE_INIT state. The device may
continue to use the IP address. If a DHCP Server is later available, and the device is able to request an IP
address, it must no longer use the old IP address.
In busy networks, a DHCP Client socket queue can fill up with non-specific DHCP broadcast packets
intended for other DHCP Client hosts. If the DHCP Client socket receive-queue fills up, any packets intended
for the device may get dropped. To avoid this problem, the DHCP Client continually clears non-specific
broadcast packets from the socket.
3.1 NetX DHCP Client Module Important Operational Notes and Limitations
3.1.1 NetX DHCP Client Module Operational Notes
Instead of the DHCP Client module creating the packet pool, the developer may prefer to supply a previously
created packet pool. To do so, enable the Use application packet pool option, then use the
nx_dhcp_packet_pool_set service to set the DHCP Client’s packet pool.
The DHCP Client verifies that the packet payload is not less than the minimum required packet size.
The IP address offered to the client should be tested for ‘uniqueness’ on the local network, since the DHCP
protocol does not require the server to check. To configure the DHCP Client to check, enable the Se nd ARP
probe option.
The DHCP Client sends a series of ARP “probes” with its assigned IP address out on the network. If any host
responds to these ARP requests/probes, the DHCP Client automatically sends a DECLINE message to the
server and restarts the DHCP protocol to request another IP address. Otherwise, the DHCP Client proceeds
to the bound state. The states of the client in the DHCP pr otocol are:
NX_DHCP_STATE_NOT_STARTED
NX_DHCP_STATE_INIT
NX_DHCP_STATE_SELECTING
NX_DHCP_STATE_REQUESTING
NX_DHCP_STATE_BOUND
NX_DHCP_STATE_RENEWING
NX_DHCP_STATE_REBINDING
R11AN0138EU0103 Rev.1.03 Page 5 of 21
May.02.19
Renesas Synergy™ Platform NetX™ DHCP Client Module Guid e
Resource
ISDE
Tab
Stacks Selection Sequence
g_dhcp_client0 NetX DHCP Client
Threads
New Stack> X-Ware> NetX> Protocols> NetX DHCP
Client
Note: If ARP probe is enabled, the NetX DHCP Client enters a temporary state called
NX_DHCP_STATE_ADDRESS_PROBING before the NX_DHCP_STATE_BOUND state.
The application can detect if the DHCP Client has completed (has an IP address) in a couple of ways. First, it
can call the nx_ip_status_check service with the NX_IP_ADDRESS_RESOLVED option. Alternatively, it
can use the nx_dhcp_state_change_notify service which notifies the application when the DHCP
Client state changes. When the DHCP Client reaches the bound state, (state == NX_DHCP_STATE_BOUND) it
has a valid IP address.
If there is a need to stop the DHCP Client thread task, call the nx_dhcp_stop service. To restart the Client,
first call the nx_dhcp_reinitialize service to clear the DHCP Client data and also clear network
parameters registered with N etX . Then, the DHCP Client is restarted with the nx_dhcp_start call.
3.1.2 NetX DHCP Client Module Limitations
• The DHCP Client does not support the INFORM_REQUEST message. The application can send this
message out using the nx_dhcp_send_request service, but the data from the Server is not extracted
and saved to the DHCP Client.
• The options supported nx_dhcp_user_option_retrieve are limited to the followi ng:
NX_DHCP_OPTION_SUBNET_MASK
NX_DHCP_OPTION_TIME_OFFSET
NX_DHCP_OPTION_GATEWAYS
NX_DHCP_OPTION_TIMESVR
NX_DHCP_OPTION_DNS_SVR
NX_DHCP_OPTION_NTP_SVR
NX_DHCP_OPTION_DHCP_LEASE
NX_DHCP_OPTION_DHCP_SERVER
NX_DHCP_OPTION_RENEWAL
NX_DHCP_OPTION_REBIND
• Refer to the following documents (also listed in the References Section) for additional limitations for this
module: NetX Dynamic Host Configuration Protocol for Clients User’s Guide for the Renesas Synergy™
Platform Latest SSP Release Notes.
4. Including the NetX DHCP Client Module in an Application
This section descr ibes how to include the NetX DH CP Client module in an applicati on using the Synergy
Software Platform (SSP) Configurator in your Integrated Solution Development Environment (ISDE).
Note: It is assumed you are familiar the steps to creating a project, adding threads, adding a stack to a
thread, and configuring a block within the stack. If you are unfamiliar with any of these items, refer to
the SSP User’s Manual to learn how to manage each of these important steps in creating SSP-based
To add the NetX DHCP Client module to an application, simply add it to a thread using the stacks selection
sequence listed in the following table. (The default name for the NetX DHCP Client is g_dhcp_client0.
This name can be changed in the associated Properties window.)
Table 3. NetX DHCP Client Module Selection Sequence
When the NetX DHCP Client module on g_dhcp_client0 is added to the thread stack as shown in the
following figure, the configurator automatically adds the needed lower-level NetX components and dri ver s. A
applications.
R11AN0138EU0103 Rev.1.03 Page 6 of 21
May.02.19
Renesas Synergy™ Platform NetX™ DHCP Client Module Guid e
driver or NetX component needing additional configuration is box-text highlighted in Red. Modules with a
Gray band are individual standalone modules. Modules with a Blue band are shared or common; they only
need to be added once to be used by multiple stacks. Modules with a Pink band can require additional lower
level drivers. Sometimes these drivers are opt ion al or recom mended, and this information is indicated with
the inclusion of this text in the block. If additional lower-level dri vers are required, the module description
includes Add in the text. Clicking a Pink-banded module brings up the New icon and displays possible
choices for selection.
Figure 2. NetX DHCP Client Module Stack
5. Configuring the NetX DHCP Client Module
The NetX DHCP Client module must be configured by the user for the desired operation. The SSP
configuration window automatically identifies (by highlighting the block in red) any required configuration
selections, such as interrupts or operating m odes, configured for lo wer-level modules to enabl e successful
operation. Only properties that can be changed without causing conflict are available for modification.
Properties that are locked with a lock icon in the Properties wi ndow in the ISDE are not available for changes.
This approach simplifies the configuration process and makes it much less error-prone than previous ‘manual’
approaches to configuration. The available configuration settings and defaults for all the user-accessible
properties are given in the properties tab within the SSP Configurator and are shown in the following tables for
easy reference.
One of the properties m ost often identified as requiring a change is the interrupt priority; this configuratio n
setting is available within the Properties window of the associated module. Simply select the indicated module
to view it in the properties wind o w; the interrupt settings are often towards the bottom of the properties list, so
scroll down until the y becom e availabl e. Also no te th at the interrupt prior ities list ed in t he Properties window
in the ISDE indicate the validity of the setting based on the MCU targeted (CM4 or CM0+). This level of detail
is not included in the following configuration pr operties tables b ut is eas ily visib le when configuri ng interruptpriority levels in the ISDE.
R11AN0138EU0103 Rev.1.03 Page 7 of 21
May.02.19
Loading...