 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Domain Name System (DNS) provides a distributed database that contains mapping between domain names and physical IP addresses. The database is referred to as "distributed" because there is no single entity on the Internet that contains the complete mapping. An entity that maintains a portion of the mapping is called a DNS server. The Internet is composed of numerous DNS servers, each of which contains a subset of the database. DNS servers also respond to DNS client requests for domain name mapping information, only if the server has the requested mapping. The DNS client protocol for NetX and NetX Duo provides the application with services to request mapping information from one or more DNS Servers.
Unsupported Features
Cache support has not been tested in this version of SSP.
IPV6 has not been tested for NetX Duo in this version of SSP.
The NetX/NetX Duo DNS Client module defines API functions for connecting, binding, listening, sending and receiving. A complete list of the available API functions, an example API function call and a short description of each can be found in the following table.
NetX/NetX Duo DNS Client Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_dns_create | nx_dns_create(&my_dns, &my_ip, "My DNS");Create a DNS Client instance. |
| nx_dns_delete | nx_dns_delete(&my_dns);Delete a DNS Client instance. |
| nx_dns_packet_pool_set | nx_dns_packet_pool_set(&my_dns, &packet_pool);Set the DNS Client packet pool. |
| nx_dns_get_serverlist_size | nx_dns_get_serverlist_size (&my_dns, 5);Return the size of the DNS Client's Server list. |
| nx_dns_info_by_name_get | nx_dns_info_by_name_get(&my_dns, "www.abc1234.com", ip_address, &port, 200);Return IPv4 address, port querying on input host name. |
| nx_dns_ipv4_address_by_name_get | nx_dns_ipv4_address_by_name_get(&client_dns,(UCHAR *)"www.my_example.com",record_buffer,sizeof(record_buffer),&record_count,500); Look up the IPv4 address for the specified host name. |
| nx_dns_host_by_address_get | nx_dns_host_by_address_get(&my_dns, IP_ADDRESS(192.2.2.10),&resolved_name[0], BUFFER_SIZE, 450);Look up a host name from a specified IP address (supports only IPv4 addresses). |
| nx_dns_host_by_name_get | nx_dns_host_by_name_get(&my_dns, "www.my_example.com", &ip_address, 4000);Look up an IP address from the host name (supports only IPv4 addresses). |
| nx_dns_server_add | nxd_dns_server_add(&my_dns, server_address);Add a DNS Server of the specified IP address to the Client's Server list (supports only IPv4). |
| nx_dns_server_get | nx_dns_server_get(&my_dns, 5, &my_server_address);Return the DNS Server in the Client list at the specified index (supports only IPv4 addresses). |
| nx_dns_server_remove | nx_dns_server_remove(&my_dns, IP_ADDRESS(202,2,2,13));Remove a DNS Server from the Client list (supports only IPv4 addresses). |
| nx_dns_server_remove_all | nx_dns_server_remove_all(&my_dns);Remove all DNS Servers from the Client list. |
| nx_dns_cache_initialize | nx_dns_cache_initialize(&my_dns, &dns_cache, 2048);Initialize a DNS Cache. |
| nx_dns_cache_notify_clear | nx_dns_cache_notify_clear(&my_dns);Clear the DNS cache full notify function. |
| nx_dns_cache_notify_set | nx_dns_cache_notify_set(&my_dns, cache_full_notify_cb);Set the DNS cache full notify function. |
| nx_dns_cname_get | nx_dns_cname_get(&client_dns, (UCHAR *)"www.my_example.com ",record_buffer, sizeof(record_buffer), 500);Look up the canonical domain name for the input domain name alias. |
| nx_dns_authority_zone_start_get | nx_dns_authority_zone_start_get(&client_dns, (UCHAR *)"www.my_example.com",record _buffer, sizeof(record_buffer),&record_count, 500);Look up the start of a zone of authority associated with the specified host name. |
| nx_dns_domain_name_server_get | nx_dns_domain_name_server_get(&client_dns, (UCHAR *)" www.my_example.com ",record_buffer, sizeof(record_buffer),&record_count, 500);Look up the authoritative name servers for the input domain zone |
| nx_dns_domain_mail_exchange_get | nx_dns_domain_mail_exchange_get(&client_dns, (UCHAR *)" www.my_example.com",record_buffer, sizeof(record_buffer),&record_count, 500);Look up the mail exchange associated with the specified host name. |
| nx_dns_domain_service_get | nx_dns_domain_service_get(&client_dns, (UCHAR *)"www.my_example.com ",record_buffer, sizeof(record_buffer),&record_count, 500);Look up the service(s) associated with the specified host name. |
| nxd_dns_ipv6_address_by_name_get** | nxd_dns_ipv6_address_by_name_get(&client_dns,(UCHAR *)"www.my_example.com",record__buffer, sizeof(record_buffer),&record_count, 500);Look up the IPv6 address from the specified host name. |
| nxd_dns_host_by_address_get** | nxd_dns_host_by_address_get(&my_dns, &host_address,resolved_name, sizeof(resolved_name), 4000);Look up a host name from the input IP address (supports both IPv4 and IPv6 addresses). |
| nxd_dns_host_by_name_get** | nxd_dns_host_by_name_get(&my_dns, "www.my_example.com", &ip_address, 4000,NX_IP_VERSION_V4);Look up an IP address from the input host name (supports both IPv4 and IPv6 addresses). |
| nxd_dns_server_add** | nxd_dns_server_add(&my_dns, &server_address);Add the input DNS Server to the Client server list (supports both IPv4 and IPv6 addresses). |
| nxd_dns_server_get** | nxd_dns_server_get(&my_dns, 5, &my_server_address);Return the DNS Server in the Client list at the specified index (supports both IPv4 and IPv6 addresses). |
| nxd_dns_server_remove** | nxd_dns_server_remove(&my_dns,& server_ADDRESS);Remove a DNS Server of the specified IP address from the Client list (supports both IPv4 and IPv6 addresses). |
**This API is only available in NetX Duo DNS Client. For definitions of of NetX Duo specific data types, see the NetX Duo User Guide for the Renesas Synergy™ Platform.
Status Return Values
| Name | Description |
|---|---|
| NX_SUCCESS | API Call Successful. |
| NX_DNS_NO_SERVER | Client server list is empty. |
| NX_DNS_QUERY_FAILED | No valid DNS response received. |
| NX_DNS_NEED_MORE_RECORD_BUFFER | Input buffer size insufficient to hold the minimum data. |
| NX_PTR_ERROR* | Invalid IP or DNS pointer. |
| NX_CALLER_ERROR* | Invalid caller of this service. |
| NX_DNS_ERROR | Internal error in DNS Client processing. |
| NX_DNS_PARAM_ERROR | Invalid non-pointer input. |
| NX_DNS_CACHE_ERROR | Invalid Cache pointer. |
| NX_DNS_TIMEOUT | Timed out on obtaining DNS mutex. |
| NX_DNS_BAD_ADDRESS_ERROR | Null input address. |
| NX_DNS_INVALID_ADDRESS_TYPE | Index points to invalid address type (for example, IPv6). |
| NX_DNS_IPV6_NOT_SUPPORTED | Cannot process record with IPv6 disabled. |
| NX_NOT_ENABLED | Client not configured for this option. |
| NX_DNS_DUPLICATE_ENTRY | DNS Server is already in the Client list. |
| NX_NO_MORE_ENTRIES | No more DNS Servers allowed (list is full). |
| NX_DNS_SERVER_NOT_FOUND | Server not in client list. |
DNS Messages
The NetX DNS Client module creates the IP instance, enables UDP services in NetX, and initializes the network driver while registering a valid IP address. The module creates an UDP socket for sending and receiving DNS messages to DNS servers listening on port 53 for DNS queries.
To obtain a mapping, the DNS client prepares a DNS query message containing the name or the IP address to be resolved. The message goes to the first DNS server in the server list. If the server has a mapping, it replies to the DNS client using a DNS response message containing the requested mapping. If the server does not respond, the DNS client queries the next server on its list until all its DNS servers have been queried. If no response is received from all its DNS servers, the DNS client retransmits the DNS message starting back at the top of the server list. DNS queries are sent until the retransmission timeout expires. Until a response is received, each iteration down the list of servers doubles the retransmission timeout until the maximum transmission timeout is reached. This timeout is set in the Maximum duration to retransmit a DNS query (seconds) property. The default value is 64 seconds; the maximum number of times the DNS client iterates down the server list, which is set by the Maximum retries for a server property and defaults to 3.
The typical NetX DNS Client queries are:
nx_dns_host_by_name_get service.nx_dns_host_by_address_get service.nxd_dns_host_by_name_get service. (This is only available in the NetX Duo DNS Client.)nxd_dns_host_by_address_get service. (This is only available in the NetX Duo DNS Client.)The NetX Duo DNS Client module still supports nx_dns_host_by_name_get and nx_dns_host_by_address_get services. These are equivalent services, but they are limited to IPv4 network communication, so developers are encouraged to use the nxd_dns_host_by_name_get and nxd_dns_host_by_address_get services instead.
Extended DNS Resource Record Types
If the Extended RR types support property is enabled, the NetX DNS Client module also supports the following record type queries:
CNAME contains the canonical name for an alias
TXT contains a text string
NS contains an authoritative name server
SOA contains the start of a zone of authority
MX used for mail exchange
SRV contains information on the service offered by the domain
With the exception of CNAME and TXT record types, the application must supply a 4-byte aligned buffer to receive the DNS data record.
In the NetX DNS Client module, the record data is stored to make efficient use of buffer space. The following example shows a record buffer of fixed length (type AAAA record):
For queries whose record types have a variable data-length (such as NS records with variable-length host names), the NetX DNS Client module saves the data using the following methodology:
The NetX DNS Client queries use the record storage format to return the number of records saved to the record buffer; this information enables the application to extract NS records from the record buffer. After calling the nx_dns_domain_service_get with the receive_buffer pointer to the storage space, the application extracts the SRV data sequentially, taking advantage of the known size of the SRV entry:
DNS Cache
If the Cache support property is enabled, the NetX DNS Client module supports the DNS cache feature. The application must set up the DNS cache using the nx_dns_cache_initialize service. When caching is enabled, the DNS client checks the DNS cache resource records before sending a DNS query. If it finds the answer in the cache, it directly returns it to the application. Otherwise, it sends out a query message to a DNS server and waits for the reply. When the DNS client gets the response message, it adds a resource record to the cache, if there is a cache entry available.
Each cache entry is a data structure used to hold a resource record. String entries (resource record name and data) in resource records are variable length, and as such, are not stored directly in the resource record. Instead, the resource record sets a pointer to the actual memory location in the cache where the strings are stored. Strings and resource records share the cache. Records are stored from the beginning of the cache and grow towards the end of the cache. String entries start from the end of the cache and grow towards the beginning of the cache. Each string entry has a length field and a counter field. When a string entry is added to the cache, and the same string is already present in the table, the counter value is incremented and no memory is allocated for the string. The cache is considered full if no more resource records or new string entries can be added to the cache.
The NetX DNS Client requires a packet pool for transmitting DNS messages; by default, the application must set the packet pool before using DNS client services. This can either be the packet pool used by the IP instance (g_packet_pool0), or it can be a separate packet pool added to the project: Azure RTOS> NetX Duo> NetX Duo Packet Pool Instance (or Azure RTOS> NetX> NetX Packet Pool Instance in NetX DNS Client).
If the Use application packet pool is disabled, the DNS Client module creates the packet pool when the DNS client is created. The Maximum DNS queries size property determines the size of the packet payload and defaults to 512 bytes. The Packets in DNS packet pool property sets the number of packets in the DNS Client packet pool (defaults to 6).
Before sending DNS queries, the application must add one or more DNS servers to the server list kept by the DNS client. The maximum server list size is set by the Maximum number of DNS Servers in the Client server list property.
To add a DNS server, the application can use either the nx_dns_server_add service (limited to IPv4 packets) or the nxd_dns_server_add service supporting IPv4 and IPv6 packets.
In the NetX DNS Client, enabling the Client has Gateway Server should be disabled. The IP instance cannot have its gateway address by the time the DNS client is created and initialized by the configurator build process, and DNS Client IP instance gateway should not be used. To set a DNS server, it is recommended to use the nx_dns_server_add.
nx_dns_cache_initialize service with the cache memory buffer pointing to a previously defined buffer. To be notified if the cache is full, use the nx_dns_cache_notify_set service. This callback can be 'disabled' by clearing the callback using the nx_dns_cache_notify_clear service.| NetX DNS API Service (IPv4 only) | NetX Duo DNS API Service (IPv4 and IPv6 supporte) |
|---|---|
| nx_dns_host_by_name_get | nxd_dns_host_by_name_get |
| nx_dns_host_by_address_get | nxd_dns_host_by_address_get |
| nx_dns_server_get | nxd_dns_server_get |
| nx_dns_server_add | nxd_dns_server_add |
| nx_dns_server_remove | nxd_dns_server_remove |
This section describes how to include either or both the NetX and NetX Duo DNS Client module in an application using the SSP configurator.
To add the NetX/NetX Duo DNS Client module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX/NetX Duo DNS Client Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_dns0 NetX DNS Client | Threads | New Stack> X-Ware> NetX> Protocols> NetX DNS Client |
| g_dns0 NetX Duo DNS Client | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo DNS Client |
When the NetX and/or NetX Duo DNS 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 DNS 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 DNS Client Module
| ISDE Property | Value | Description |
|---|---|---|
| DNS Control Type of Service | Normal, Minimum delay, Maximum data, Maximum reliability, Minimum cost Default: Normal | DNS control type of service selection. |
| Socket fragmentation option | Don't fragment, Fragment okay Default: Don't fragment | Socket fragmentation option selection. |
| Time to live | 128 | Time to live selection. |
| **Client DNS IP version | IPv4, IPv6 Default: IPv4 | Client DNS IP version selection. |
| Maximum number of DNS Servers in Client server list | 5 | Maximum number of DNS Servers in Client server list selection. |
| Maximum DNS queries size (bytes) | 512 | Maximum DNS queries size selection. |
| Packets in DNS packet pool (units) | 16 | Packets in DNS packet pool selection. |
| Maximum retries for a server | 3 | Maximum retries for a server selection. |
| Maximum duration to retransmit a DNS query (seconds) | 64 | Maximum duration to retransmit a DNS query selection. |
| Packet allocate timeout (seconds) | 1 | Packet allocate timeout selection. |
| Client has DNS and Gateway server | Enable, Disable Default: Disable | DNS control type of service selection. |
| DNS Client IP instance gateway (use commas for separation) (Not included in NetX Duo) | 192,16,0,1 | DNS client IP instance gateway selection. |
| Use application packet pool | Enable, Disable Default: Enable | Use application packet pool selection. |
| Clear previous DNS queries from queue | Enable, Disable Default: Disable | Clear previous DNS queries from queue selection. |
| Extended RR types support | Enable, Disable Default: Disable | Extended RR types support selection. |
| Cache support | Enable, Disable Default: Disable | Cache support selection. |
| Name | g_dns0 | Module name. |
| Name of generated initialization function | dns_client_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
** Indicates properties that are only available in NetX Duo.
In some cases, settings other than the defaults for lower-level modules can be desirable. For example, it might be useful to select different MAC or IP Addresses. The configurable properties for the lower-level stack modules are provided 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) | 192,168,0,2 | IPv4 Address selection. |
| Subnet Mask (use commas for separation) | 255,255,255,0 | Subnet Mask selection. |
| Default Gateway Address (use commas for separation) | 0,0,0,0 | Default gateway address 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 function. |
| Link status change callback | NULL | Link status change callback selection. |
** Indicates properties that are only available in NetX Duo.
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 the 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 steps in using the NetX/NetX Duo DNS Client module in a typical application are:
1. Wait for valid IP address using the nx_ip_status_check API.
2. Enable DNS caching by calling the nx_dns_cache_initialize [optional].
3. Add one or more servers to the client list using the nx_dns_server_add API.
4. Send DNS name query using nxd_dns_host_by_name_get API to obtain an IP address.
5. Extract DNS server resource records using known size and arrangement of records packaged by the DNS client.
The following figure illustrates common steps in a typical operational flow diagram:
