 |
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, DHCPv6 replaces DHCP (which is limited to IPv4) for dynamic global IPv6 address assignment from a DHCPv6 Server. The DHCPv6 offers most of the same features, as well as many enhancements, and explains how the NetX Duo™ DHCPv6 Server API is used for DHCPv6 Client IPv6 address requests.
The NetX Duo DHCPv6 Server module defines APIs for creating, deleting, adding and getting server information. 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 Duo DHCP IPv6 Server Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_dhcpv6_server_create | nx_dhcpv6_server_create(&g_dhcpv6_server0, &server_ip_address, "DHCPv6 Server", &g_packet_pool0, stack_pointer, NX_DHCPV6_SERVER_THREAD_STACK_SIZE, address_declined_handler, option_request_handler);Create a DHCPv6 Server instance. |
| nx_dhcpv6_server_delete | nx_dhcpv6_client_delete(&g_dhcpv6_server0);Delete a DHCPv6 Server instance and release resources (unbind port, delete socket, timers and thread). |
| nx_dhcpv6_create_ip_address_lease | nx_dhcpv6_create_ip_address_range(&g_dhcpv6_server0, &start_ipv6_address, &end_ipv6_address, &addresses_added);Create the Server's IPv6 address lease pool. |
| nx_dhcpv6_reserve_ip_address_range | nx_dhcpv6_reserve_ip_address_range(&g_dhcpv6_server0, &start_ipv6_address, &end_ipv6_address, &addresses_reserved);Reserve the specified range of IPv6 addresses not to be leased out to a requesting Client. |
| nx_dhcpv6_add_ip_address_lease | nx_dhcpv6_add_ip_address_lease(&g_dhcpv6_server0, table_index, &lease_IP_address, T1, T2, valid_lifetime, preferred_lifetime);Copy an IPv6 lease record into the specified index into the Server table. Intended for use in non-volatile storage of IPv6 lease data. |
| nx_dhcpv6_add_client_record | nx_dhcpv6_add_client_record(&g_dhcpv6_server0, table_index, message_xid, &client_address, client_state, IP_lease_time_accrued, valid_lifetime, duid_type, duid_hardware, physical_address_msw, physical_address_lsw, duid_time, duid_vendor_number, duid_vendor_private, duid_private_length);Copy a Client record into the specified index into the Server table. Intended for use in non-volatile storage of Client IPv6 address data. |
| nx_dhcpv6_create_dns_address | nx_dhcpv6_create_dns_address(&g_dhcpv6_server0, &dns_ipv6_address);Set the DNS server address to include in network parameters sent to clients. |
| nx_dhcpv6_retrieve_client_record | nx_dhcpv6_retrieve_client_record(&g_dhcpv6_server0, table_index, message_xid, &client_address, client_state, IP_lease_time_accrued, valid_lifetime, duid_type, duid_hardware, physical_address_msw, physical_address_lsw, duid_time, duid_vendor_number, duid_vendor_private, duid_private_length);Retrieve items from the Client specified by the index into the Server table. Intended for use in non-volatile storage of Client IPv6 address data. |
| nx_dhcpv6_retrieve_ip_address_lease | nx_dhcpv6_retrieve_ip_address_lease(&g_dhcpv6_server0, table_index, &lease_IP_address, T1, T2, valid_lifetime, preferred_lifetime);Retrieve items from the IPv6 lease specified by the index into the Server table. Intended for use in non-volatile storage of IPv6 lease data. |
| nx_dhcpv6_server_interface_set | nx_dhcpv6_server_interface_set(&g_dhcpv6_server0, 0, 1);Set the interface the DHCPv6 Server will run on, and the global address the DHCPv6 Server will use in messages to Clients. By default, the DHCPv6 Server runs on the primary interface (index 0). |
| nx_dhcpv6_set_server_duid | nx_dhcpv6_set_server_duid(&g_dhcpv6_server0, NX_DHCPV6_SERVER_DUID_TYPE, NX_DHCPV6_SERVER_HW_TYPE, physical_address_msw, physical_address_lsw, duid_time);Create the Server DUID which is a required part of the DHCPv6 header and uniquely identifies the DHCPv6 Server. |
| nx_dhcpv6_server_start | nx_dhcpv6_server_start(&g_dhcpv6_server0);Start the DHCPv6 thread task. |
| nx_dhcpv6_server_suspend | nx_dhcpv6_server_suspend(&g_dhcpv6_server0);Suspend the DHCPv6 server task. |
| nx_dhcpv6_server_resume | nx_dhcpv6_server_resume(&g_dhcpv6_server0);Resume the DHCPv6 server task. |
Status Return Values
| Name | Description |
|---|---|
| NX_SUCCESS | Successful API call. |
| NX_PTR_ERROR* | Invalid pointer input. |
| NX_CALLER_ERROR* | Must be called from thread. |
| NX_DHCPV6_PARAM_ERROR | Invalid non pointer input. |
| NX_INVALID_INTERFACE | Invalid interface index input. |
| NX_DHCPV6_UNSUPPORTED_DUID_TYPE | DUID type unknown or not supported. |
| NX_DHCPV6_UNSUPPORTED_DUID_HW_TYPE | DUID hardware type unknown or not supported. |
| NX_DHCPV6_IA_ADDRESS_ALREADY_EXIST | Duplicate IA address. |
| NX_DHCPV6_REACHED_MAX_IA_ADDRESS | IA exceeds the max IAs Client can store. |
| NX_DHCPV6_INVALID_IA_ADDRESS | Invalid (for example, null) IA address in IA. |
| NX_DHCPV6_IA_ADDRESS_NOT_VALID | IPv6 address successfully assigned. |
| NX_DHCPV6_UNKNOWN_OPTION | Unknown/unsupported option code. |
| NX_DHCPV6_ALREADY_STARTED | DHCPv6 Client is already running. |
| NX_DHCPV6_NOT_STARTED | DHCPv6 Client task not started. |
| NX_DHCPV6_MISSING_REQUIRED_OPTIONS | Client missing required options. |
The NetX Duo DHCPv6 Server module creates a NetX Duo IP instance for the server and a UDP socket bound to the well-known DHCPv6 Server port 547 to listen for client requests. Before starting DHCPv6, the server needs a global IPv6 address by setting the IPv6 Global Address property in the IP NetX Duo Instance property box. (Note that this is a 128‑bit long address, compared to the 32-bit long IPv4 address.)
The DHCPv6 Server should wait for the IPv4 address to be validated using the nx_ip_status_check service, even if the server does not use this IP address for DHCPv6 messages. The driver needs to be initialized with information from the IP layer and the link needs to be enabled, all of which happens with IPv4 address-registration.
Before an application can start the DHCPv6 Server, it must create a pool of assignable IPv6 addresses using the nx_dhcpv6_create_ip_address_range service. The application must also create a server DUID (DHCP Unique Identifier, usually based on the MAC address, and is required in all DHCPv6 Server messages using the nx_dhcp_set_server_duid service. Optionally, it can set the network DNS Server to include in the DHCPv6 option data to clients using the nx_dhcpv6_create_dns_server service; now the server can be started with the nx_dhcpv6_server_start service.
The server maintains a table of IPv6 addresses, updates their status, and indicates whether any addresses are leased out. For leased out addresses, the table indicates the client to which the address is leased. The size of this table is set by the Maximum Size of the Server's IP lease table property, and should be equal to or greater than the number of IPv6 addresses in the IPv6 address pool. The server maintains another table for client records; the size of this table is set by the Size of Server's Client record table property portion of the DHCP Server properties box and should be at least the size of the IPv6 lease table. If the server receives a Client Release or Decline, the server updates the IPv6 lease table and client record table, accordingly.
The DHCPv6 Server creates two timers. The first timer keeps track of the time remaining on IPv6 addresses leased to clients. The interval at which the server checks client leases is set by the Client lease time expiration check interval property, which defaults to 60 seconds. If the server issues leases with extremely short lease-expirations, that value should be reduced to approximately 10 or 20 percent of the timeout value. If a lease timeout expires, the lease is returned to the pool of IPv6 addresses and the client record is deleted. The second timer is used to monitor client‑session inactivity; the default timeout for session inactivity timeout is 20 seconds. The interval in which the server checks its client records for an expired session inactivity timeout is the Interval for active session time update property in the NetX Duo DHCP IPv6 Common properties box, with the interval having a 3-second default time.
If the underlying hardware supports ICMPv6 checksum computation, the following values can be left disabled:
This section describes how to include either or both the NetX Duo DHCP IPv6 Server module in an application using the SSP configurator.
To add the NetX Duo DHCP IPv6 Server module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX Duo DHCP IPv6 Server Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_dhcp_server0NetX Duo DHCP IPv6 Server | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo DHPC IPv6 Server |
When the NetX Duo DHCP IPv6 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.
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 Duo DHCP IPv6 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.
Configuration Settings for the NetX Duo DHCP IPv6 Server Module
| ISDE Property | Value | Description |
|---|---|---|
| Internal thread priority | 1 | Internal thread priority selection. |
| Client lease time expiration check interval (seconds) | 60 | Client lease time expiration check interval selection. |
| DHCPv6 packet receive timeout (seconds) | 1 | DHCPv6 packet receive timeout selection. |
| Server preference ranking for clients | 0 | Server preference ranking for clients selection. |
| Maximum options to extract from a client message | 6 | Maximum options to extract from a client message selection. |
| Server interval for first client IP address renewal attempt (seconds) | 2000 | Server interval for first client IP address renewal attempt selection. |
| Server interval for second client IP address renewal attempt (seconds) | 3000 | Server interval for second client IP address renewal attempt selection. |
| Time interval after which client IP is deprecated (seconds) | 2*NX_DHCPV6_DEFAULT_T1_TIME | Time interval after which client IP is deprecated selection. |
| Time interval after which leased IP in invalid (seconds) | 2*NX_DHCPV6_DEFAULT_PREFERRED_TIME | Time interval after which leased IP in invalid selection. |
| Maximum server status option message size (bytes) | 100 | Maximum server status option message size selection. |
| Maximum Size of the Server's IP lease table (count) | 100 | Maximum Size of the Server's IP lease table selection. |
| Size of the Server's Client record table (count) | 120 | Size of the Server's Client record table selection. |
| Server socket fragmentation option | Don't fragment, fragment okay Default: Don't fragment | Server socket fragmentation option selection. |
| Vendor assigned unique ID | abcdefghijklmnopqrstuvwxyz | Vendor assigned unique ID selection. |
| Private vendor ID | 0x12345678 | Private vendor ID selection. |
| Size of Vendor ID buffer (bytes) | 48 | Size of vendor ID buffer selection. |
| Client request success message: granted | IA OPTION GRANTED | Client request successmessage: granted selection. |
| Client request failure message: Failure unspecified | IA OPTION NOT GRANTED - FAILURE UNSPECIFIED | Client request failure message: Failure unspecified selection. |
| Client request failure message: No addresses available | IA OPTION NOT GRANTED - NO ADDRESSES AVAILABLE | Client request failure message: No addresses available selection. |
| Client request failure message: Invalid client request | IA OPTION NOT GRANTED - INVALID CLIENT REQUEST | Client request failure message: Invalid client request selection. |
| Client request failure message: Client not on link | IA OPTION NOT GRANTED - CLIENT NOT ON LINK | Client request failure message: Client not on link selection. |
| Client request failure message: Client must use multicast | IA OPTION NOT GRANTED - CLIENT MUST USE MULTICAST | Client request failure message: Client must use multicast selection. |
| Session inactivity timeout (seconds) | 20 | Session inactivity timeout selection. |
| Name | g_dhcpv6_server0 | Module name. |
| Internal thread stack size (bytes) | 4096 | Internal thread stack size selection. |
| Name of address declined handler function | dhcpv6_address_declined_handler | Name of address declined handler function selection. |
| Name of option request handler | dhcpv6_option_request_handler | Name of option request handler selection. |
| Name of generated initialization function | dhcpv6_server_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
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 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. |
Configuration Settings for the NetX Duo DHCP IPv6 Common Instance
| ISDE Property | Value | Description |
|---|---|---|
| Type of Service for UDP requests | Normal, Minimum delay, Maximum data, Maximum reliabililty, Minimum cost Default: Normal | Type of service UDP requests selection. |
| Time to live | 128 | Time to live selection. |
| Packet Queue depth | 5 | Packet queue depth selection. |
| packet alocation timeout (seconds) | 3 | Packet allocation timeout selection. |
| Interval for active session time update (seconds) | 3 | Interval for active session time update selection. |
Configuration Settings for the 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 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.
The steps in using the NetX Duo DHCP IPv6 Server module in a typical application are:
nx_dhcpv6_set_server_duid API.nx_dhcpv6_create_ip_address_range API.nx_dhcpv6_create_dns_address API [Optional].nx_dhcpv6_server_start API. nx_dhcpv6_server_suspend API.nx_dhcpv6_server_resume API [Optional].nx_dhcpv6_server_delete API.The following figure illustrates common steps in a typical operational flow diagram:
