Synergy Software Package User's Manual
NetX/NetX Duo DHCP Server

Table of Contents

NetX/NetX Duo DHCP Server Introduction

The Dynamic Host Configuration Protocol (DHCP) is designed to completely automate DHCP Server allocation and dynamic IP address allocation through leasing an IP address to a client for a specified time.

In IPv6 networks, the DHCP protocol is of no use because it is limited to IPv4. Therefore, the DHCPv6 is the protocol used for dynamic global IPv6 address assignment from a DHCPv6 Server. This guide covers only the IPv4 version of DHCP, but applies to NetX™ and NetX™ Duo. A note will clearly identify where there are any differences in use between NetX and NetX Duo. To simplify wording in this document, NetX DHCPv4 will be used to stand for NetX and NetX Duo DHCP for IPv4.

NetX/NetX Duo DHCP Server Module Features

  • The NetX DHCP is compliant with RFC2132, RFC2131 and related RFCs.
  • Provides high-level APIs for:
    • Creating and deleting a DHCPv4 Server instance
    • Setting network parameters for DHCPv4 Server messages to the client
    • Creating a pool of assignable IP addresses
    • Starting and stopping the DHCP Server task thread
nx_dhcp_server_BD.png
NetX/NetX Duo DHCP Server Module Block Diagram
Note
In the figure above, the NetX (or NetX Duo) Network Driver modules has multiple implementation options available. See the description just after the module stack figure in Including the NetX/NetX Duo DHCP Server Module in an Application for additional details.

NetX/NetX Duo DHCP Server Module APIs Overview

The NetX DHCP Server defines APIs for creating, deleting, removing, starting, and stopping the server, for creating the pool of assignable IP addresses, and for setting up the network information for the client. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

NetX/NetX Duo DHCP Server Module API Summary

Function Name Example API Call and Description
nx_dhcp_server_create nx_dhcp_server_create(&dhcp_server, &server_ip, pointer,
DEMO_SERVER_STACK_SIZE, SERVER_IP_ADDRESS_LIST, "DHCP server", &server_pool);
Create a DHCP Server instance.
nx_dhcp_create_server_ip_address_list nx_dhcp_create_server_ip_list (&dhcp_server, iface_index,
START_IP_ADDRESS_LIST, END_IP_ADDRESS_LIST, &addresses_added);
Create pool of available IP addresses to assign to DHCP Clients on the specified network index.
nx_dhcp_clear_client_record nx_dhcp_clear_client_record (&dhcp_server, &dhcp_client_ptr);
Remove Client record in the Server database.
nx_dhcp_set_interface_network_parameters nx_dhcp_set_interface_network_parameters(&dhcp_server, iface_index,
NX_DHCP_SUBNET_MASK, NX_DHCP_DEFAULT_GATEWAY,
NX_DHCP_DNS_SERVER);
Set DHCP options for adding critical network parameters on specified interface in messages to Clients.
nx_dhcp_server_delete nx_dhcp_server_delete(&dhcp_server);
Delete a DHCP Server instance.
nx_dhcp_server_start nx_dhcp_server_start(&dhcp_server);
Start or resume DHCP Server processing.
nx_dhcp_server_stop nx_dhcp_server_stop(&dhcp_server);
Stop DHCP server processing.
Note
For details on operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the associated Azure RTOS User's Manual in the References section.

Status Return Values

Name Description
NX_SUCCESS Successful DHCP call.
NX_PTR_ERROR* Invalid pointer input.
NX_DHCP_PARAMETER_ERROR Invalid non-pointer input.
NX_DHCP_INADEQUATE_PACKET_POOL_PAYLOAD Packet payload too small error.
NX_DHCP_NO_SERVER_OPTION_LIST Missing option list; cannot create Server.
NX_DHCP_SERVER_BAD_INTERFACE_INDEX Index does not match addresses.
NX_DHCP_INVALID_IP_ADDRESS Invalid IP address or network interface for creating Server address list.
NX_DHCP_INVALID_IP_ADDRESS_LIST Illogical start/end IP addresses for Server list.
NX_DHCP_INVALID_NETWORK_PARAMETERS Invalid network parameters for DHCP messages to Client.
NX_DHCP_SERVER_ALREADY_STARTED The DHCP instance has already been started.
NX_DHCP_SERVER_NOT_STARTED DHCP Server not started.
NX_CALLER_ERROR* Invalid caller of service.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.
  • These are error codes which are only returned if error checking is enabled. Refer to the NetX User Guide for the Renesas Synergy™ Platform or NetX Duo User's Guide for the Renesas Synergy™ Platform for more details on error-checking services in NetX and NetX Duo, respectively.

NetX/NetX Duo DHCP Server Module Operational Overview

The DHCP server utilizes the UDP protocol to receive DHCP Client requests and transmit responses. It handles all details of creating an IP instance, initializing the driver, creating the UDP socket, and binding to the well-known DHCP port 67 to receive client requests.

The DHCP Server is assigned a packet pool when it is created. It can share the packet pool used by the IP instance (the IP default packet pool) or the module can create a separate one for the server. The packet payload must be large enough to include DHCP data, IP and UDP headers, and the physical frame header. DHCP data size is set by the Size of the BOOT Buffer (bytes) property, which defaults to 548 bytes.

Before starting the DHCP Server, the application must create a pool of assignable IP addresses; it does so by calling the nx_dhcp_create_server_ip_address_listservice. This service takes as input a starting IP address and an ending IP address. The server verifies the addresses are local network addresses. The DHCP Server services are interface-specific, including creating the IP address list and setting network parameters. The assumed network interface the DHCP Server is running on is the primary interface (index is zero). It fills a table of IP addresses sequentially starting at the starting IP address. The addresses_added pointer input returns the number of addresses added, which is equal to or less than the size of this table. The IP address table size is defined by the Maximum size of an IP addresses list property, which defaults to 20. There is one such table for each network interface on which the DHCP Server is receiving DHCP Client requests.

The DHCP Server keeps a record of each client (or rather the client's DISCOVER request) in its client record table. The record lives for as long as the client keeps the assigned IP address. If the client fails to renew, or fails to respond to the DHCP protocol before reaching the bound (IP address assigned) state, the record is deleted. One table holds all client records from all network interfaces on which the server receives DHCP requests. The size of the table is set by the Size of client record table (units) property, which defaults to 50.

Once the DHCP Server is running and has created client records and assigned IP addresses, it periodically checks the time remaining on each of the client IP leases. The length of the IP lease is set in the Client IP address lease time (seconds) property. The default value of 0xFFFFFFFF is essentially a permanent lease. To assign leases of finite length, set the lease to a more standard time. An example lease time might be 10 days (0x0d5930 or 874,800 seconds). The interval on which the DHCP Server checks the time remaining on assigned IP leases is set to 1000 seconds*.* If a lease expires, the server simply removes the client record from the client record table, and returns that IP address back to the pool of assignable IP addresses. No message is sent to the client.  The client should have initiated renew or rebind requests before its lease expired; or possibly the client has left the network.

The DHCP Server also keeps an inactivity timeout on each client session. When a client sends a packet, the inactivity timeout for that client is reset. The interval on which the DHCP Server checks the time remaining is the Fast‑periodic timer interval to check valid sessions (ticks), which defaults to 10 ticks*.* This session timeout is this value multiplied by the ratio of ticks per second to produce a session timeout of 10 seconds. If a client record session time out expires, that client's IP address is returned to the pool of assignable IP addresses and the client record is cleared. No message is sent to the client.

NetX/NetX Duo DHCP Server Module Important Operational Notes and Limitations

NetX/NetX Duo DHCP Server Module Operational Notes

  • The options the DHCP Server provides to the client for critical network parameters are defined in the Server option list property and set to the default value 1 3 6, which are the option codes for the Subnet Mask, Router/Gateway address, and DNS Server IP address, respectively.  The number of options is set in the Server option list size property, which defaults to 3.
  • The DHCP Type (Option 53) and DHCP Server Identifier (Option 54) are the DHCP parameters the server must supply to the DHCP Client.

NetX/NetX Duo DHCP Server Module Limitations

  • The choice of options the DHCP Server provides are limited to some or all the following: Subnet Mask (Option 1), Router/Gateway address (Option 3), and DNS Server IP address (Option 6). Therefore, setting the Server option list size to greater than three has no effect. Setting the list of options to an option other than 1,3 or 6 has no effect.
  • The NetX DHCP Server does not verify that its assignable IP addresses are not in use elsewhere in the network. It is expected that the client will check the uniqueness of its IP address it is assigned.
  • The NetX DHCP Server does not support the FORCE RENEW message.
  • The Relay agent field of the DHCP header is left null because the NetX DHCP Server does not support out‑of‑network DHCP requests.
  • The DHCP Server does not correctly update the time remaining on the assigned IP leased. The slow periodic timer interval is set to 1000 ticks. Internally, that value is converted to seconds, so the actual interval on which the server checks the IP lease timeout is about 1000 * 100 assuming there are 100 ticks per second on the NetX device.  If the client lease time is left at the default value of 0xFFFFFFFF, this is a permanent lease until the client decides to release it and should not be affected by this bug.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the NetX/NetX Duo DHCP Server Module in an Application

This section describes how to include either or both the NetX and NetX Duo DHCP Server module in an application using the SSP configurator.

Note
It is assumed you are familiar with 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 first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the NetX/NetX Duo DHCP Server module to an application, simply add it to a thread using the stacks selection sequence given in the following table.

NetX/NetX Duo DHCP Server Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_dhcp_Server0NetXDHCPServer Threads New Stack> X-Ware> NetX> Protocols> NetXDHCPServer
g_dhcp_Server0NetX Duo DHCP IPv4Server Threads New Stack> X-Ware> NetX Duo> Protocols> NetX Duo DHCP IPv4Server

When the NetX and/or NetX Duo DHCP Server module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

nx_dhcp_server_MS.png
NetX/NetX Duo DHCP Server Module Stack

In the stack above, the NetX Network Driver (or NetX Duo Network Driver in a NetX Duo stack) has not been populated yet. There are multiple possible selections for the Network Driver; they are not all provided so as not to needlessly complicate the figure and the following configuration tables. The available options depend on the MCU target, but some typical options include:

  • NetX Duo Port using PPP on nxd_ppp
  • NetX Port ETHER on sf_el_nx
  • NetX Port using Cellular Framework on sf_cellular_nsal_nx
  • NetX Port using PPP on nx_ppp
  • NetX Port using Wi-Fi Framework on sf_wifi_nsal_nx

Configuring the NetX/NetX Duo DHCP Server Module

The NetX/NetX Duo DHCP Server 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 modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. 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.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table values. This helps to orient you and can be a useful hands-on approach to learning the ins and outs of developing with SSP.

Configuration Settings for the NetX/NetX Duo DHCP Server Module

ISDE Property Value Description
Internal thread priority 1 Internal thread priority selection.
Packet allocate timeout (seconds) 2 Packet allocate timeout selection.
Fast periodic timer interval to check valid sessions (ticks) 10 Fast periodic timer interval to check valid sessions selection.
DHCP Client Session timeout - multiple of Fast periodic interval (seconds) 10 DHCP Client session timeout selection.
Client IP address default lease time (seconds) 0xFFFFFFFF Client IP address lease time selection.
Slow periodic timer inverval to check IP lease expiration (seconds) 1000 Slow periodic timer inverval to check IP lease expiration selection.
Size of the array to contain options in client request (units) 12 Size of the array containing current requested options selection.
Server option list (optional - use space for separation 1 3 6 Module server option list selection.
Server option list size (optional) 3 Server option list size selection.
Size of the server host main buffer (bytes) 32 Size of the server host main buffer selection.
Size of the current client hostname buffer (byte) 32 Size of the current client hostname buffer selection.
Maximum size of an IP addresses list (units) 20 Maximum size of an IP addresses list selection.
Size of the client record table (units) 50 Size of the client record table selection.
Size of the BOOT buffer (bytes) 548 Size of the BOOT buffer selection.
Name g_dhcp_server0 Module name.
Internal thread stack size (bytes) NetX Default: 2048

NetX Duo Default: 4096 		Internal thread stack size selection.
Name of generated initialization function nx_dhcp_server_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

In some cases, settings other than the defaults for stack modules can be desirable. For example, it might be useful to select different Ethernet interface pins and resets. The configurable properties for the lower-level stack modules are given in the following sections for completeness and as a reference. 

Note
Most of the property settings for lower-level modules are intuitive and usually can be determined by inspection of the associated properties window from the SSP configurator.

Configuration Settings for the NetX/NetX Duo DHCP Server Lower-Level Modules

Only a small number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module:

Configuration Settings for the NetX/NetX Duo IP Instance

ISDE Property Value Description
Name g_ip0 Module name.
IPv4 Address (use commas for separation) 0,0,0,0 IPv4 Address selection.
Subnet Mask (use commas for separation) 255,255,255,0 Subnet Mask selection.
**IPv6 Global Address (use commas for separation) 0x2001, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1 IPv6 global address selection.
**IPv6 Link Local Address (use commas for separation, All zeros means use MAC address) 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 IPv6 link local address selection.
IP Helper Thread Stack Size (bytes) 2048 IP Helper Thread Stack Size (bytes) selection.
IP Helper Thread Priority 3 IP Helper Thread Priority selection.
ARP Enable ARP selection.
ARP Cache Size in Bytes 512 ARP Cache Size in Bytes selection.
Reverse ARP Enable, Disable

Default: Disable 		Reverse ARP selection.
TCP Enable, Disable

Default: Enable 		TCP selection.
UDP Enable, Disable

Default: Enable 		UDP selection.
ICMP Enable, Disable

Default: Enable 		ICMP selection.
IGMP Enable, Disable

Default: Enable 		IGMP selection.
IP fragmentation Enable, Disable

Default: Disable 		IP fragmentation selection.
Name of generated initialization function ip_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

** Indicates properties that are only available in NetX Duo.

Configuration Settings for the NetX/NetX Duo DHCP Common Instance

ISDE Property Value Description
Type of Service for UDP requests Normal, Minimum delay, Maximum data, Maximum reliability, Minimum cost

Default: Normal 		Type of service UDP requests selection.
Fragmentation option Don't fragment, Fragment okay

Default: Don't fragment 		Fragmentation option selection.
Time to live 128 Time to live selection.
Packet Queue depth 5 Packet queue depth selection.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the NetX/NetX Duo Common Instance

ISDE Property Value Description
Name of generated initialization function nx_common_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the NetX/NetX Duo Packet Pool Instance

ISDE Property Value Description
Name g_packet_pool0 Module name.
Packet Size in Bytes 640 Packet size selection.
Number of Packets in Pool 16 Number of packets in pool selection.
Name of generated initialization function packet_pool_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

NetX/NetX Duo DHCP Server Module Clock Configuration

The ETHERC peripheral module uses PCLKA as its clock source. The PCLKA frequency is set using the SSP configurator clock tab prior to a build, or by using the CGC interface at run-time.

NetX/NetX Duo DHCP Server Module Pin Configuration

The ETHERC peripheral module uses pins on the MCU device to communicate to external devices. I/O pins must be selected and configured by the external device as required.  The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the I2C pins.

Note
The selected operation mode determines the peripheral signals available and the MCU pins required.

Pin Selection for the ETHERC Module

Resource ISDE Tab Pin selection Sequence
ETHERC Pins Select Peripherals> Connectivity:ETHERC> ETHERC1.RMII
Note
The selection sequence assumes ETHERC1 is the desired hardware target for the driver.

Pin Configuration Settings for the ETHERC1

Property Value Description
Operation Mode Disabled, Custom, RMII

Default: Disabled 		Select RMII as the Operation Mode for ETHERC1.
Pin Group Selection Mixed, _A only

Default: _A only 		Pin group selection.
REF50CK P701 REF50CK pin.
TXD0 P700 TXD0 pin.
TXD1 P406 TXD1 pin.
TXD_EN P405 TXD_EN pin.
RXD0 P702 RXD0 pin.
RXD1 P703 RXD1 pin.
RX_ER P704 RX_ER pin.
CRS_DV P705 CRS_DV pin.
MDC P403 MDC pin.
MDIO P404 MDIO pin.
Note
The example settings are for a project using the S7G2 Synergy MCU Group and the SK-S7G2 Kit. Other Synergy MCUs and other Synergy Kits may have different available pin configuration settings.

Using the NetX/NetX Duo DHCP Server Module in an Application

The steps in using the NetX/NetX Duo DHCP Server module in a typical application are:

  1. Create a pool of assignable IP addresses using the nx_dhcp_create_server_ip_address_list API.
  2. Set network parameters that will be returned by the server using the nx_dhcp_set_interface_network_parameters API.
  3. Start the DHCPv4 server with the nx_dhcp_server_start API.

The following figure illustrates common steps in a typical operational flow diagram:

nx_dhcp_server_TA.png
Flow Diagram of a Typical NetX/NetX Duo DHCP Server Module Application