Renesas NetX, NetX Duo User Manual
Application Note
Renesas Synergy™ Platform
NetX™ and NetX Duo™ DNS Client Module Guide
Introduction
This module guide will enable you to effectively use a m odul e i n 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 an efficient starting point.
References to more detailed API descripti ons and suggestions of other application projects t hat il l ust rat e
more advanced uses of the module are included in t his document and should be valuable resources for
creating more complex designs.
Domain Name System (DNS) is a distributed database containing the mapping between domain names and
physical IP addresses. The database is refer red t o as “distributed” because no single entity on the Internet
contains the complete mapping. An entity, called a DNS server, maintains a portion of the mapping.
Numerous DNS servers exist on the Internet, 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 se rvices to
request mapping information from one or more D NS Servers.
Note: Except where noted, the NetX Duo DNS Client is identical to the NetX DNS Client in application set-
up and running of DNS queries. To set up the IP instance for IPv6 in NetX Duo, see the NetX Duo
Key elements related to the NetX and NetX Duo DNS Client module implementation on the Renesas
Synergy Platform are provided. The primary focus is to add and configure the NetX and NetX Duo DNS
Client Module to a Renesas Synergy Platform project. For details, see NetX™ Domain Name System (DNS)
Client User Guide for the Renesas Synergy™ Platform or NetX Duo™ Domain Name System (DNS) Cli en t
User Guide for the Renesas Synergy™ Platform. These documents reside in the X-Ware™ Component
Documents for Renesas Synergy™ zip available for download at the Renesas Synergy Gallery site
(www.renesas.com/synergy/software).
User Guide for the Renesas Synergy™ Platform.
Contents
1. NetX and NetX Duo DNS Client Module Features .................................................................... 2
2. NetX and NetX Duo DNS Client Module APIs Overview ........................................................... 3
3. NetX and NetX Duo DNS Client Module Operational Overview ................................................ 5
3.1 NetX and NetX Duo DNS Client Module Important Operat i onal Notes and Limitations ......................... 8
3.1.1 NetX and NetX Duo DNS Client Module Operational Notes ................................................................. 8
3.1.2 NetX and NetX Duo DNS Client Module Limitations ............................................................................. 9
4. Including the NetX and NetX Duo DNS Client Module in an Application ................................... 9
5. Configuring the NetX and NetX Duo DNS Client Module ........................................................ 10
5.1 Configuration Settings for the NetX DNS Client Lower-Lev el M odules ................................................ 11
5.2 NetX and NetX Duo DNS Client Module Clock Configurat ion .............................................................. 14
5.3 NetX and NetX Duo DNS Client Module Pin Configuration .................................................................. 14
6. Using the NetX and NetX Duo DNS Client Module in an Application ...................................... 14
7. The NetX and NetX Duo DNS Client Module Application Project ........................................... 15
8. Customizing the NetX and NetX Duo DNS Client Module for a Target Application ................ 17
9. Running the NetX and NetX Duo DNS Client Module Application Project .............................. 18
R11AN0178EU0101 Rev.1.01 Page 1 of 22
Jan.04.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ DNS Client Module Guide
10. NetX and NetX Duo DNS Client Module Conclusion ............................................................... 20
11. NetX and NetX Duo DNS Client Module Next Steps ............................................................... 20
12. NetX and NetX Duo DNS Client Module Reference Information ............................................. 20
Revision History .............................................................................................................................. 22
1. NetX and NetX Duo DNS Client Module Features
• Optional creation of separate packet pool for DNS operations
• Support of Type A, AAAA, and NS DNS queries
• Support of CNAME, SRV, TXT, SOA, and MX DNS resource types
• Support for DNS cache for storing and retrieving ca ched DNS data
• High-level APIs for
Name and IP address lookup
Adding and removing DNS servers
Creating and deleting the DNS instance
• NetX DNS is compliant with the following RFCs:
RFC1034 Domain Names – Concepts And Facilities
RFC1035 Domain Names — Implementation And Specification
RFC1480 The US Domain
RFC 2782 A DNS RR for specifying the locat i on of services (DNS SRV)
RFC 3596 DNS Extensions to Support I P Version 6
Figure 1. NetX and NetX Duo DNS Client Module
R11AN0178EU0101 Rev.1.01 Page 2 of 22
Jan.04.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ DNS Client Module Guide
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”,
Return IPv4 address, port querying on input host name.
nx_dns_ipv4_address_by_na
nx_dns_ipv4_address_by_name_get(&client_dns,(UCHAR
Look up the IPv4 address for the specified host name.
nx_dns_host_by_address_ge
nx_dns_host_by_address_get(&my_dns, IP_ADDRESS(192.2.2.10),
addresses).
nx_dns_host_by_name_get
nx_dns_host_by_name_get(&my_dns, “www.my_example.com”,
addresses).
nx_dns_server_add
nxd_dns_server_add(&my_dns, server_address);
(supports only IPv4).
nx_dns_server_get
nx_dns_server_get(&my_dns, 5, &my_server_address);
only IPv4 addresses).
nx_dns_server_remove
nx_dns_server_remove(&my_dns, IP_ADDRESS(202,2,2,13));
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
Look up the canonical domain name for the input domai n nam e al ias.
2. NetX and NetX Duo DNS Cli ent Module APIs Overview
The NetX and NetX Duo DNS Client module defines A PIs for connecting, binding, listening, sending, an d
receiving. A complete list of the available API s, an example API call, and a short description of each API can
be found in the following table. The end of the summary table lists nx services unique to NetX and NetX Duo
BSD. Following the API summary table is a list of status return values.
Table 1. NetX and NetX Duo DNS Client Module API Summary
&ip_address, &port,
200);
me_get
t
*)"www.my_example.com",
record_buffer,sizeof(record_buffer),&record_count,500);
&resolved_name[0], BUFFER_SIZE, 450);
Look up a host name from a specified IP address (supports o nly IPv4
&ip_address, 4000);
Look up an IP address from the host name (supports only IPv4
Add a DNS Server of the specified IP address to the Client ’s Server list
Return the DNS Server in the Client list at the specif i ed i ndex (supports
Remove a DNS Server from the Client list (supports only IPv4
",
record_buffer, sizeof(record_buffer), 500);
R11AN0178EU0101 Rev.1.01 Page 3 of 22
Jan.04.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ DNS Client Module Guide
Function Name
Example API Call and Description
nx_dns_authority_zone_start
nx_dns_authority_zone_start_get(&client_dns, (UCHAR
name.
nx_dns_domain_name_serve
nx_dns_domain_name_server_get(&client_dns, (UCHAR *)"
nx_dns_domain_mail_exchan
nx_dns_domain_mail_exchange_get(&client_dns, (UCHAR *)"
Look up the mail exchange associated with the specified host name.
nx_dns_domain_service_ge
nx_dns_domain_service_get(&client_dns, (UCHAR
nxd_dns_ipv6_address_by_
nxd_dns_ipv6_address_by_name_get(&client_dns,
Look up the IPv6 address from the specified host name.
nxd_dns_host_by_address_
nxd_dns_host_by_address_get(&my_dns, &host_address,
nxd_dns_host_by_name_get
nxd_dns_host_by_name_get(&my_dns, “www.my_example.com”,
IPv6 addresses).
nxd_dns_server_add**
nxd_dns_server_add(&my_dns, &server_address);
nxd_dns_server_get**
nxd_dns_server_get(&my_dns, 5, &my_server_address);
both IPv4 and IPv6 addresses).
nxd_dns_server_remove**
nxd_dns_server_remove(&my_dns,& server_ADDRESS);
_get
r_get
ge_get
t
name_get**
*)"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
www.my_example.com ",
record_buffer, sizeof(record_buffer),
&record_count, 500);
Look up the authoritative name servers for the input domain zone
www.my_example.com
",record_buffer, sizeof(record_buffer),
&record_count, 500);
*)“www.my_example.com ",
record_buffer, sizeof(record_buffer),
&record_count, 500);
Look up the service(s) associated with the specifie d host name.
(UCHAR *)"www.my_example.com",
record__buffer, sizeof(record_buffer),
&record_count, 500);
get**
**
Note: For details on operation and definitions of t he f unct i on data structures, typedefs, defines, API dat a,
API structures, and function variables, review the associated Express Logic User’s Manual listed in
the References section.
**This API is only available in NetX Duo DNS Client. For definitions of of NetX Duo spe cif i c data
types, see the NetX Duo User Guide for the Renesas Synergy™ Plat form.
resolved_name, sizeof(resolved_name), 4000);
Look up a host name from the input IP address (support s both IPv4 and
IPv6 addresses).
&ip_address, 4000,
NX_IP_VERSION_V4);
Look up an IP address from the input host name (supports both IPv4 and
Add the input DNS Server to the Client server list (supports both IPv4 and
IPv6 addresses).
Return the DNS Server in the Client list at the specif i ed i ndex (supports
Remove a DNS Server of the specified IP address from the Client list
(supports both IPv4 and IPv6 addresses).
R11AN0178EU0101 Rev.1.01 Page 4 of 22
Jan.04.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ DNS Client Module Guide
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 insufficien t 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 (e.g. I Pv6)
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
Table 2. Status Return Values
Note: Lower-level drivers may return common error codes. See SSP User’s Manual API References for the
associated module for a definition of all relevant status return values.
* These error codes are only returned if error checking is enabled. For details on error-checking
services, see NetX User Guide for the Renesas Synergy™ Platform or NetX Duo User Guide f or t he
Renesas Synergy™ Platform in NetX and NetX Duo, respectively
.
3. NetX and NetX Duo DNS Client Module Operational Overview
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 I P address
to be resolved. The message goes to the first D NS server in the server list. If the server has a mappin g, 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 DN S client retransmits the DNS message
starting back at the top of the server list. DNS queries are sent until the retransmission timeout expi res. 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:
• IPv4 address lookups (type A) by using the nx_dns_host_by_name_get service.
• Reverse lookups of IP addresses (type PTR querie s) to obtain web host names using the
nx_dns_host_by_address_get service.
• IPv6 address lookups (type AAAA) or IPv4 address lookups (type A), specified in the IP address data
type input, in the nxd_dns_host_by_name_get service. (This is only available in the NetX Duo DNS
Client.)
• Reverse lookups of IP addresses (type PTR querie s) to obtain web-host names using the
nxd_dns_host_by_address_get service. (This is only av ai labl e i n the NetX Duo DNS Client.)
R11AN0178EU0101 Rev.1.01 Page 5 of 22
Jan.04.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ DNS Client Module Guide
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 networ k
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, t he Net X 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
Except for CNAME and TXT record types, the application must su pply 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 reco rd).
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:
• Organizes the buffer supplied in the DNS Client query into fixed-length data and unstructu red memory
areas.
• Organizes the top of the memory buffer into 4-byte aligned record entries.
• For each record entry, holds the IP address and a pointer to the variable-length data for that IP address.
• Stores variable-length data for each IP address in unstructured area memory starting at the end of the
memory buffer.
• Saves variable-length data for each suc cessive record entry in the next area of memory, adjacent to t he
previous record entries’ variable data.
• ‘Grows’ the variable data towards the structured area of memory holding record entries until there is
insufficient memory to store another record entry and variable data (see following figure).
R11AN0178EU0101 Rev.1.01 Page 6 of 22
Jan.04.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ DNS Client Module Guide
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 buff er. A fter
calling the nx_dns_domain_service_get with the receive_buffer pointer to the storage space, the
application extracts the SRV data sequential l y, taking advantage of the known size of the SRV entry:
NX_DNS_SRV_ENTRY *nx_dns_srv_entry_ptr[RECORD_COUNT];
status = nx_dns_domain_service_get(&client_dns,
(UCHAR *)"www.my_example.com",
&record_buffer[0], BUFFER_SIZE, &record_count,
NX_IP_PERIODIC_RATE);
for(i =0; i< record_count; i++)
{
nx_dns_srv_entry_ptr[i] =
(NX_DNS_SRV_ENTRY *)(record_buffer + i * sizeof(NX_DNS_SRV_ENTRY));
}
DNS Cache
If the Cache support property is enabled, the NetX DNS Client m odule supports the DNS cache feature. The
application must set up the DNS cache using the nx_dns_cache_initialize service. When c aching is enabled,
the DNS client checks the DNS cache resource recor ds bef ore 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 act ual memory location in the cache where the strings a re
stored. Strings and resource records share the cach e. Records are stored from the beginning of the cac he
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.
R11AN0178EU0101 Rev.1.01 Page 7 of 22
Jan.04.19
Loading...