Synergy Software Package User's Manual
NetX Duo NAT

Table of Contents

NetX Duo NAT Introduction

The IP Network Address Translation (NAT) solves the problem of a limited number of Internet IPv4 addresses that arises when multiple devices need access to the Internet, but only one IPv4 Internet address is assigned by the Internet Service Provider (ISP). A NAT-enabled router is installed between the public and private network to translate between internal private IPv4 addresses and assigned public IPv4 address, so devices on the private network can share the same public IPv4 address.

NetX Duo NAT Module Features

  • NetX NAT supports the following RFCs:
    • RFC 2663: IP Network Address Translator (NAT) Terminology and Considerations
    • RFC 3022: Traditional IP Network Address Translator (Traditional NAT)
    • RFC 4787: Network Address Translation (NAT) Behavioral Requirements for Unicast User Datagram Protocol (UDP)
  • NetX NAT provides the following high level APIs:
    • Creating and deleting a NAT server
    • Enabling and disabling NAT in NetX Duo
    • Set callbacks for NAT to notify application if NAT entry table is full
    • Creating static inbound entries in the NAT table
nxd_nat_BD.png
NetX Duo NAT Module Block Diagram
Note
In the figure above, The NetX Duo Network Driver modules has multiple implementation options available. See the description just after the module stack figure in Including the NetX Duo NAT Module in an Application for additional details.

NetX Duo NAT Module APIs Overview

The NetX Duo NAT Module defines APIs for creating, deleting and enabling operations. 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 NAT Module API Summary

Function Name Example API Call and Description
nx_nat_create nx_nat_create(nat_ptr, ip_ptr, global_interface_index, nat_cache, NX_NAT_ENTRY_CACHE_SIZE); 
Create a NAT Instance in which the network interface is the global interface (not the local/private network) with the specified network index.
nx_nat_delete nx_nat_delete (nat_ptr);
Delete a NAT instance.
nx_nat_enable nx_nat_enable (nat_ptr);
Enable the NAT server.
nx_nat_disable nx_nat_disable (nat_ptr);
Disable the NAT server.
nx_nat_cache_notify_set nx_nat_cache_notify_set(nat_ptr, cache_full_notify_cb);
Set the NAT cache full notify function to a user‑defined notify function.
nx_nat_inbound_entry_create nx_nat_inbound_entry_create(nat_ptr, entry_ptr, IP_ADDRESS(192,168,2,2), 5001, 5001, NX_PROTOCOL_TCP);
Create an inbound translation table entry. This is typically used by application servers to allow clients to initiate a connection externally.
nx_nat_inbound_entry_delete nx_nat_inbound_entry_delete(nat_ptr, delete_entry_ptr);
Delete an inbound translation table entry.
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 NAT function
NX_PTR_ERROR* Invalid input pointer parameter
NX_CALLER_ERROR* Invalid caller (for example, must be a thread) of a service
NX_NAT_PARAM_ERROR* Invalid non pointer input
NX_NAT_CACHE_ERROR* Cache memory not 4 byte aligned, or is too small
NX_NAT_PORT_UNAVAILABLE Invalid external port for creating static entry
NX_NAT_ENTRY_NOT_FOUND Entry to delete is not found in Cache table
NX_NAT_ENTRY_TYPE_ERROR* Invalid entry (not static) to delete
Note
Lower-level drivers may return common error codes. See 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 Duo NAT Module Operational Overview

A NAT-enabled router typically has two network interfaces: one connected to the public Internet, the other connected to the private network. A typical router in this setup is responsible for routing IP datagrams between the private network and the public network based on the destination IP address. A NAT-enabled router performs address translation before routing an IPv4 datagram between the public and the private interface. Translation is established for each TCP or UDP session, based the internal source address and source port number, as well as the external destination address and destination port number. For the ICMP echo request and response datagram, the Internet Control Message Protocol (ICMP) query ID is used instead of the port number.

Typically, connections across the NAT boundary are initiated by the hosts on the private network sending outbound packets to an external host. In these cases, hosts are usually assigned dynamic (temporary) IP addresses. It is also possible to have connections initiated in the opposite direction if the private network has 'servers' (such as HTTP or FTP) that accept client requests from the external network. NAT applications typically assign these local hosts a static (permanent) IP address port.

The following three illustrations and accompanying steps illustrate the sequence of events when sending packets through a NAT router.

nxd_nat_CS.png
NetX Duo NAT Module Connection Start

Step 1. Client transmits a TCP SYN message to the web server. The Client address on the private network is 192.168.1.15, port number 6732; the destination address is 128.15.54.3, port number 80. 

Step 2. The packet from the Client is received on the private network interface by the NAT router.  The outbound traffic rule applies to the packet: the sender's (Client's) address is translated to the NAT router's public IP address 202.151.25.14, and sender (Client) source port number is translated to the TCP port number 2015 for transmission out on the public interface.    

Step 3. The packet is then transmitted over the Internet and ultimately reaches its destination host 128.15.54.3. On the receiving side, notice in the following figure that the packet appears to have originated from 202.151.25.14, port number 2015 when it was in fact relayed from that IP address and port.

nxd_nat_NT.png
NetX Duo NAT Module Network Address Translation

Step 4. Host 128.15.54.3 sends back a response packet with the NAT router's Internet address as its destination. 

Step 5. The packet reaches the NAT router.  Since this is an in-bound packet, the in-bound translation rules apply:  the destination address is changed back (translated) to the original sender's (Client's) IP address: 192.168.1.15, destination port number 6732.

Step 6. The packet is then forwarded to the Client through the interface connected to the internal network.

nxd_nat_RP.png
NetX Duo NAT Module Packet Return Path

When sending packets through a NAT router, the sender's Internet network address and port number is not exposed to other hosts on the public Internet. 

To keep track of the network address translations for all active connections between local and external networks, the NetX Duo NAT-enabled router maintains a translation table with information about each private host connection that includes source and destination IP address and port number.

NetX Duo NAT is intended for use on an IPv4 router. For the NAT to work, the NetX Duo must be configured to forward-receive packets to an internal NetX Duo NAT handler. The handler determines whether the packet is received from the global network (inbound) or from the private network (outbound).

  • For inbound packets, the handler determines whether it can forward (consume) the packet to the host on the private (local) network. To make the determination, the handler looks for a matching entry based on the packet destination address and port in the NAT translation table. If a matching entry is found, the handler translates the destination address to the matching private host IP address and port, and sends the packet to that host. If it cannot find an entry, it lets the NetX Duo process the packet as normal; as if the packet was intended for the NAT device itself. 
  • For outbound packets, the NAT handler checks the destination IP address to determine whether it can forward the packet out onto the global network or whether NetX Duo should handle the packet as it does normally. If the packet has a broadcast or loopback destination address, or an IP address which does not match the NAT device global network address, the NAT handler lets the NetX Duo handle the packet. Otherwise, the handler looks for a matching entry of the sender's IP and address in the translation table. If it finds a match, it translates the IP address and port to the local IP address and port, and forwards (consumes) the packet to the local host. If a previous entry is not found, the NAT creates an entry in the NAT translation table, translates the sender's IP address for the global interface and forwards the packet to the external host.

NetX Duo NAT Module Important Operational Notes and Limitations

NetX Duo NAT Module Operational Notes

  • To enable the NAT, add the NetX Duo Source component to the Configurator pane, and set the NAT property of NetX Duo Source. The prebuilt NetX Duo source library does not have NAT enabled.
  • The Maximum Physical Interfaces property, also in NetX Duo Source, must be set to 2, assuming one private network and one global network. Auto-generated code creates the IP instance using the global network IP address, and attach the secondary interface as the private network interface.
  • There must be two network driver instances. The project for this module uses the NetX Port ETHER framework (sf_el_nx) for both interfaces but one network interface can be on Wi-Fi, or other network media. If using two sf_el_nx driver instances, ensure their names are not the same and that one references channel 0 and the other channel 1. The MAC addresses for a dual-ported driver are in a single NetX Port Ether configuration, so no need to change these but ensure they are not identical between Channel 0 and Channel 1.
  • The function specified in the Name of the generated initialization function property must attach the secondary interface and create the NAT instance-if the Auto initialization property of the NAT instance is enabled in the configurator (by default it is enabled). The Private IPv4 Address property is the local IP address of the NAT device (server). The Global network interface index specifies the network interface the global network uses. By default, this index is set to zero (the primary interface of the IP instance), and the secondary interface is the local network (interface index 1).
  • If Auto Initialization is disabled, then the NAT application must attach a secondary interface and create a NAT instance before using any NAT service. After attaching the secondary interface, the application should wait for the internal NetX Duo processing to enable the link on that interface using the nx_ip_interface_status_check API (see the module guide project example for how this is done).
  • At runtime, the NetX Duo NAT Framework also creates a 4-byte aligned table, or cache, to store NAT translation entries. The size of the cache is set by the Cache Size property of the NAT instance. The default value is 1024 bytes (a NAT translation record is 28 bytes). The minimum size of a NetX Duo NAT Translation table is three entries. This value is set in the Minimum count for translation entry property which defaults to 3 but should be set to a larger number in a busy network with many local hosts.
  • By default, entries created by the NAT server when receiving inbound or outbound packets are dynamic entries. They are assigned a timeout value (Timeout for translation_entry property); the default value of 240 seconds is the timeout recommended by RFC 2663. When an entry timeout expires, the entry is marked for deletion. However, because the NetX Duo NAT server implementation does not have a timer, it checks the entire table for expired entries and deletes them when adding a new entry to the table. If there are no entries that have expired, and the table is full, the NetX Duo NAT server notifies the application with the cache full callback. The application can set this callback with the nx_nat_cache_notify_set service.
  • To create static entries that never expire, the application can use the nx_nat_inbound_entry_create service. These entries can only be created for inbound packets and are sometimes referred to as 'inbound rules.' The entries are intended for server applications, to allow clients to initiate connection sessions with the server. Internally, the NAT verifies whether the global and local ports requested in the inbound rule are available. To delete these entries, the application calls the nx_nat_inbound_entry_delete service.
  • The NetX Duo NAT is configured with a range of TCP, UDP and ICMP translation ports to create unique local address: port entries for local hosts connecting with outside hosts.
    • TCP ports available for TCP translation ports are between the minimum value ( Minimum assigned port number for outbound TCP packets property) and the maximum value ( Maximum assigned port number for outbound TCP packets property).
    • Similarly, for UDP entries ports, Minimum assigned port number for outbound UDP packets and Maximum assigned port number for outbound UDP packets properties.
    • ICMP packets do not have ports; instead, the ICMP ID can be used as the entry translation port, Minimum ICMP query identifier and Maximum ICMP query identifier properties.
  • To start NetX Duo forwarding packets using the NAT protocol, the application calls the nx_nat_enable service. To suspend NetX forwarding, the application calls the nx_nat_disable service.
  • Once the NAT is enabled, the NAT thread entry application lets the internal processing for NAT handle packets transmission between the global and local networks. It can create inbound rules at any time to allow a host on the global network to reach a local host, as is typically done for servers on the local network.

NetX Duo NAT Module Limitations

  • Internet Group Management Protocol (IGMP) is not supported. NetX Duo NAT supports only TCP, UDP and ICMP.
  • NAT protocol does not apply to IPv6 packet transmission.
  • NetX Duo NAT does not include DNS or DHCP services, although NetX Duo NAT can integrate those services with its NAT operations.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the NetX Duo NAT Module in an Application

This section describes how to include either or both the NetX Duo NAT 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 Duo NAT module to an application, simply add it to a thread using the stacks selection sequence given in the following table.

NetX Duo NAT Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_nat0NetX Duo NAT Threads New Stack> X-Ware> NetX Duo> Protocols> NetX Duo NAT

When the NetX Duo NAT 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.

nxd_nat_MS.png
NetX Duo NAT 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 Duo NAT Module

The NetX Duo NAT 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 Duo NAT Module

ISDE Property Value Description
Minimum count for translation entry 3 Minimum count for translation entry selection
Timeout for translation entry (ticks) 240 Timeout for translation entry selection
Minimum assigned port number for outbound TCP packets 20000 Minimum assigned port number for outbound TCP packets selection
Maximum assigned port number for outbound TCP packets 30000 Maximum assigned port number for outbound TCP packets selection
Minimum assigned port number for outbound UDP packets 20000 Minimum assigned port number for outbound UDP packets selection
Maximum assigned port number for outbound UDP packets 30000 Maximum assigned port number for outbound UDP packets selection
Minimum ICMP query identifier 20000 Minimum ICMP query identifier selection
Maximum ICMP query identifier 30000 Maximum ICMP query identifier selection
Name g_nat0 Module name
Cache size (bytes) 1024 Cache size selection
Private IPv4 Address (use commas for separation) 192,168,0,2 Private IPv4 Address selection
Private IPv4 Netmask (use commas for separation) 255, 255, 255, 0 Private IPv4 Netmask selection
Global network interface index 0 Global network interface index selection
Name of generated initialization function nat_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 IP addresses and subnet masks. 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 Duo NAT 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 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.

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
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 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 Duo NAT 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 Duo NAT 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 and the SK-S7G2 Kit. Other Synergy MCUs and other Synergy Kits may have different available pin configuration settings.

Using the NetX Duo NAT Module in an Application

The following example assumes that a system is already established with a working IP, ARP, ICMP, TCP and UDP enabled, and that the link is running.

The steps in using the NetX Duo NAT module in a typical application are:

  1. Wait for the IP instance to initialize the driver and have a valid IP address using the nx_ip_status_check API for the primary ("global") interface.
  2. Wait for the IP secondary ("local") interface to also have a valid IP address at this point using the nx_ip_interface_status_check API.
  3. Set the cache full callback to be notified when the NAT translation table it full by calling the nx_nat_cache_notify_set API [Optional].
  4. Start packet forwarding by the IP layer in NetX as per NAT protocol by calling the nx_nat_enable API.  The IP thread task and NAT services handle the rest.
  5. Add static entries as desired (for example server applications that are waiting for client requests) by calling the nx_nat_inbound_entry_create [Optional]. Note this can be done before or after enabling NAT services.
  6. Suspend NAT by calling the nx_nat_disable API.
  7. Delete NAT by calling the nx_nat_delete API.

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

nxd_nat_TA.png
Flow Diagram of a Typical NetX Duo NAT Module Application