 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Dynamic Host Configuration Protocol (DHCP) is used 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™ component. Supplying the IP address poses no problem if the IP address is known to the 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 dynamically obtain an IP address.
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.
The NetX/NetX Duo 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. A list of the key API functions, an example API function call and a short description of each can be found in the following table. Additional function calls are described in the NetX DHCP Client User's Manual as describe in the note below the table. A table of status return values follows the API summary table.
NetX/NetX Duo DHCP Client Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_dhcp_create | nx_dhcp_create(&my_dhcp, &my_ip, "My DHCP");Create a DHCP instance. |
| nx_dhcp_clear_broadcast_flag | nx_dhcp_clear_broadcast_flag(&my_dhcp, NX_TRUE);Clear broadcast flag on Client messages. |
| nx_dhcp_delete | nx_dhcp_delete(&my_dhcp);Delete a DHCP instance. |
| 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 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 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);Clear DHCP client network parameters and clear IP address and gateway registered with the IP instance. |
| nx_dhcp_request_client_ip | nx_dhcp_request_client_ip(&my_dhcp, IP(192,168,0,6), NX_TRUE);Request a specific IP address. |
| nx_dhcp_send_request | nx_dhcp_send_request(&my_dhcp, NX_DHCP_TYPE_INFORMREQUEST);Send DHCP message to server (only INFORM_REQUEST is allowed). |
| nx_dhcp_server_address_get | nx_dhcp_server_address_get(&dhcp_0, &server_address);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, my_state_change);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,NX_DHCP_OPTION_DNS_SVR,dns_ip_string, &size);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. |
| 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_client0, 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. |
| nx_dhcp_client_create_record | nx_dhcp_client_create_record(&g_dhcp_client0)This fills in a client record structure associated with the DHCP Client based on Client lease data. |
| nx_dhcp_client_restore_record | nx_dhcp_client_restore_record(&g_dhcp_client, 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 time remaining on its lease. |
Status Return Values
| 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. |
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) should not be enabled; 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 packet payload size must be large enough to include DHCP data, IP, UDP headers, and the physical frame header.
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.
The DHCP client module can register a callback to add options to the DHCP protocol using the nx_dhcp_user_option_add_callback_set API function. The DHCP option 60 (Vendor Class Identifier), and DHCP option 61 (Client Identifier), as well as other options, can be added for DHCP request using the registered callback. The DHCP module can chain multiple options and the options must fit in the normal payload. The Synergy configurator provides a default DHCP Option 60 addition callback. To enable the default callback, the DHCP Option addition and DHCP Option addition function properties must be set to Enable in the configurator.
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 Send 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 protocol 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
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 NetX. Then, the DHCP Client is restarted with the nx_dhcp_start call.
This section describes how to include either or both the NetX and NetX Duo DHCP Client module in an application using the SSP configurator.
To add the NetX/NetX Duo DHCP Client module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX/NetX Duo DHCP Client Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_dhcp_client0 NetX DHCP Client | Threads | New Stack> X-Ware> NetX> Protocols> NetX DHCP Client |
| g_dhcp_client0 NetX Duo DHCP IPv4 Client | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo DHCP IPv4 Client |
When the NetX and/or NetX Duo DHCP Client 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.
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:
The NetX/NetX Duo 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 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.
Configuration Settings for the NetX/NetX Duo DHCP Client Module
| ISDE Property | Value | Description |
|---|---|---|
| Internal thread priority | 3 | Internal thread priority selection. |
| Internal thread stack size (bytes) | NetX Default: 2048 NetX Duo Default: 4096 | Internal thread stack size (bytes) selection. |
| Timeout between DHCP messages processed (seconds) | 1 | Timeout between DHCP messages processed (seconds) selection. |
| Use BOOTP | Enable, Disable Default: Disable | Use BOOTP selection. |
| Send ARP probe | Enable, Disable Default: Disable | Send ARP probe selection. |
| ARP probe wait time (seconds) | 1 | ARP probe wait time selection. |
| Minimum ARP probe wait time (seconds) | 1 | Minimum ARP probe wait time selection. |
| Minimum ARP probe wait time (seconds) | 2 | Minimum ARP probe wait time selection. |
| ARP probe count | 2 | ARP probe count selection. |
| Maximum retransmission timeout (seconds) | 64 | Maximum retransmission timeout (seconds) selection. |
| Minimum renew timeout (seconds) | 60 | Minimum renew timeout (seconds) selection. |
| Minimum retransmission timeout (seconds) | 4 | Minimum retransmission timeout (seconds) selection. |
| Client packet payload size (bytes) | 592 | Client packet payload size (bytes) selection. |
| Number of packets in internal packet pool | 5 | Number of packets in internal packet pool selection. |
| Persistent client state | Enable, Disable Default: Disable | Persistent client state selection. |
| Use application packet pool | Enable, Disable Default: Disable | Use application packet pool selection. |
| Maximum message size support | Enable, Disable Default: Disable | Maximum message size support selection. |
| DHCP options buffer size (bytes) | 312 | DHCP options buffer size (bytes) selection. |
| Maximum DHCP client state record on an interface | 1 | Maximum DHCP client state record on an interface selection. |
| Wait before restarting the configuration process (seconds) | 10 | Wait before restarting the configuration process selection. |
| Name | g_dhcp_client0 | Module name. |
| Name of generated initialization function | dhcp_client_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
| *DHCP Option addition | Enable, Disable Default: Enable | Enable or Disable feature to add DHCP Option to DHCP message. |
| *DHCP Option addition function | Enable, Disable Default: Enable | Enable or Disable Option Addition function. |
| *Name of the DHCP option addition function | dhcp_user_option_add_client0 | Name for the option add function provided by the user. |
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.
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. |
| Link status change callback | Default: NULL | Name of user defined callback function if needed- otherwise set as NULL. |
** 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. |
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. |
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. |
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.
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.
Pin Selection for the ETHERC Module
| Resource | ISDE Tab | Pin selection Sequence |
|---|---|---|
| ETHERC | Pins | Select Peripherals> Connectivity:ETHERC> ETHERC1.RMII |
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. |
The following example assumes a system that is already established with a working and enabled IP, ARP and UDP, and the link is running. Additionally, set the DHCP features for the DHCP Client (request specific IP address, clear the broadcast flag, set the interface on which DHCP Client runs, or set callback to configure the user options) before starting the DHCP Client. [Optional]
The steps in using the NetX/NetX Duo DHCP Client module in a typical application are:
nx_dhcp_start API.nx_ip_status_check (a NetX library service call) or check for the bound state in the DHCP Client state-change callback function.nx_dhcp_stop API. nx_dhcp_reinitialize API and then call the nx_dhcp_start API. [Optional]The following figure illustrates common steps in a typical operational flow diagram:
