Chapter 2 - Installation and Use of Azure RTOS NetX

This chapter contains a description of various issues related to installation, setup, and use of the high-performance network stack Azure RTOS NetX.

Host Considerations

Embedded development is usually performed on Windows or Linux (Unix) host computers. After the application is compiled, linked, and the executable is generated on the host, it is downloaded to the target hardware for execution.

Usually the target download is done from within the development tool's debugger. After download, the debugger is responsible for providing target execution control (go, halt, breakpoint, etc.) as well as access to memory and processor registers.

Most development tool debuggers communicate with the target hardware via on-chip debug (OCD) connections such as JTAG (IEEE 1149.1) and Background Debug Mode (BDM). Debuggers also communicate with target hardware through In-Circuit Emulation (ICE) connections. Both OCD and ICE connections provide robust solutions with minimal intrusion on the target resident software.

As for resources used on the host, the source code for NetX is delivered in ASCII format and requires approximately 1 Mbytes of space on the host computer's hard disk.

Target Considerations

NetX requires between 5 KBytes and 45 KBytes of Read-Only Memory (ROM) on the target. Another 1 to 5 KBytes of the target's Random Access Memory (RAM) are required for the NetX thread stack and other global data structures.

In addition, NetX requires the use of two ThreadX timer objects and one ThreadX mutex object. These facilities are used for periodic processing needs and thread protection inside the NetX protocol stack.

Product Distribution

Azure RTOS NetX can be obtained from our public source code repository at https://github.com/azure-rtos/netx/.

The following is a list of several important files in the repository:

  • nx_api.h: C header file containing all system equates, data structures, and service prototypes.
  • nx_port.h: C header file containing all development tool- and target-specific data definitions and structures.
  • demo_netx.c: C file containing a small demo application.
  • nx.a (or nx.lib): Binary version of the NetX C library that is distributed with the standard package. |

NetX Installation

You can installed NetX by cloning the GitHub repository to your local machine. The following is typical syntax for creating a clone of the NetX repository on your PC:

    git clone https://github.com/azure-rtos/netx

Alternatively you can download a copy of the repository using the Download button on the GitHub main page.

You will also find instructions for building the NetX library on the front page of the online repository.

Important

Application software needs access to the NetX library file (usually nx.a or nx.lib) and the C include files nx_api.h, and nx_port.h. This is accomplished either by setting the appropriate path for the development tools or by copying these files into the application development area.

Using NetX

To use NetX, the application code must include nx_api.h during compilation and link with the NetX library nx.a (or nx.lib).

The following are the four required steps for building a NetX application:

  1. Include the nx_api.h file in all application files that use NetX services or data structures.
  2. Initialize the NetX system by calling nx_system_initialize from the tx_application_define function or an application thread.
  3. Create an IP instance, enable the Address Resolution Protocol (ARP), if necessary, and any sockets after nx_system_initialize is called.
  4. Compile application source and link with the NetX runtime library nx.a (or nx.lib). The resulting image can be downloaded to the target and executed!

Troubleshooting

Each NetX port is delivered with one or more samples that execute on an actual network or via a simulated network driver. It is always a good idea to get the sample system running first.

If the sample system does not run properly, perform the following operations to narrow the problem:

  1. Determine how much of the sample is running.
  2. Increase stack sizes in any new application threads.
  3. Recompile the NetX library with the appropriate debug options listed in the configuration option section.
  4. Examine the NX_IP structure to see if packets are being sent or received.
  5. Examine the default packet pool to see if there are available packets.
  6. Ensure the network driver is supplying ARP and IP packets with its headers on 4-byte boundaries for applications requiring IP connectivity.
  7. Temporarily bypass any recent changes to see if the problem disappears or changes. Such information should prove useful to our support engineers.

Follow the procedures outlined in the Customer Support Center topic to send the information gathered from the troubleshooting steps.

Configuration Options

There are several configuration options when building the NetX library and the application using NetX. The configuration options can be defined in the application source, on the command line, or within the nx_user.h include file, unless otherwise specified.

Important

Options defined in nx_user.h are applied only if the application and NetX library are built with NX_INCLUDE_USER_DEFINE_FILE defined.

The following sections list the configuration options available in NetX.

System Configuration Options

Option Description
X_DEBUG Defined, enables the optional print debug information available from the RAM Ethernet network driver.
NX_DISABLE_ERROR_CHECKING Defined, removes the basic NetX error checking API and improves performance. API return codes that are not affected by disabling error checking are listed in bold typeface in the API definition. This define is typically used after the application is debugged and when its use improves performance and decreases code size.
NX_DRIVER_DEFERRED_PROCESSING Defined, enables deferred network driver packet handling. This allows the network driver to place a packet on the IP instance and have the real processing routine called from the NetX internal IP helper thread.
NX_ENABLE_EXTENDED_NOTIFY_SUPPORT Enables more callback hooks in the stack. These callback functions are used by the BSD wrapper layer. By default this option is not defined.
NX_ENABLE_SOURCE_ADDRESS_CHECK Defined, enables the source address of incoming packet to be checked. By default this option is disabled.
NX_LITTLE_ENDIAN Defined, performs the necessary byte swapping on little endian environments to ensure the protocol headers are in proper big endian format. Note the default is typically setup in nx_port.h.
NX_MAX_PHYSICAL_INTERFACES Specifies the total number of physical network interfaces on the device. The default value is 1 and is defined in nx_api.h. A device must have at least one physical interface. Note this does not include the loopback interface.
NX_PHYSICAL_HEADER Specifies the size in bytes of the physical header of the frame. The default value is 16 (based on a typical 14-byte Ethernet frame aligned to 32-bit boundary) and is defined in nx_api.h. The application can override the default by defining the value before nx_api.h is included, such as in nx_user.h.

ARP Configuration Options

Option Description
NX_ARP_DEFEND_BY_REPLY Defined, allows NetX to defend its IP address by sending an ARP response.
NX_ARP_DEFEND_INTERVAL Defines the interval, in seconds, the ARP module sends out the next defend packet in response to an incoming ARP message that indicates an address in conflict.
NX_ARP_DISABLE_AUTO_ARP_ENTRY Renamed to NX_DISABLE_ARP_AUTO_ENTRY. Although it is still being supported, new designs are encouraged to use NX_DISABLE_ARP_AUTO_ENTRY.
NX_ARP_EXPIRATION_RATE Specifies the number of seconds ARP entries remain valid. The default value of zero disables expiration or aging of ARP entries and is defined in nx_api.h. The application can override the default by defining the value before nx_api.h is included.
NX_ARP_MAC_CHANGE_NOTIFICATION_ENABLE Renamed to NX_ENABLE_ARP_MAC_CHANGE_NOTIFICATION. Although it is still being supported, new designs are encouraged to use NX_ENABLE_ARP_MAC_CHANGE_NOTIFICATION.
NX_ARP_MAX_QUEUE_DEPTH Specifies the maximum number of packets that can be queued while waiting for an ARP response. The default value is 4 and is defined in nx_api.h.
NX_ARP_MAXIMUM_RETRIES Specifies the maximum number of ARP retries made without an ARP response. The default value is 18 and is defined in nx_api.h. The application can override the default by defining the value before including nx_api.h.
NX_ARP_UPDATE_RATE Specifies the number of seconds between ARP retries. The default value is 10, which represents 10 seconds, and is defined in nx_api.h. The application can override the default by defining the value before including nx_api.h.
NX_DISABLE_ARP_AUTO_ENTRY Defined, disables entering ARP request information in the ARP cache.
NX_DISABLE_ARP_INFO Defined, disables ARP information gathering.
NX_ENABLE_ARP_MAC_CHANGE_NOTIFICATION Defined, allows ARP to invoke a callback notify function on detecting the MAC address is updated.

ICMP Configuration Options

Option Description
NX_DISABLE_ICMP_INFO Defined, disables ICMP information gathering.
NX_DISABLE_ICMP_RX_CHECKSUM Disables the ICMP checksum computation on received ICMP packets. This option is useful when the network interface driver is able to verify the ICMP checksum, and the application does not use the IP fragmentation feature. By default this option is not defined.
NX_DISABLE_ICMP_TX_CHECKSUM Disables ICMP checksum computation on transmitted ICMP packets. This option is useful where the network interface driver is able to compute the ICMP checksum, and the application does not use the IP fragmentation feature. By default this option is not defined.

IGMP Configuration Options

Option Description
NX_DISABLE_IGMP_INFO Defined, disables IGMP information gathering.
NX_DISABLE_IGMPV2 Defined, disables IGMPv2 support, and NetX supports IGMPv1 only. By default this option is not set and is defined in nx_api.h.
NX_MAX_MULTICAST_GROUPS Specifies the maximum number of multicast groups that can be joined. The default value is 7 and is defined in nx_api.h. The application can override the default by defining the value before nx_api.h is included.

IP Configuration Options

Option Description
NX_DISABLE_FRAGMENTATION Defined, disables IP fragmentation and reassembly logic.
NX_DISABLE_IP_INFO Defined, disables IP information gathering.
NX_DISABLE_IP_RX_CHECKSUM Defined, disables checksum logic on received IP packets. This is useful if the network device is able to verify the IP header checksum, and the application does not use IP fragmentation.
NX_DISABLE_IP_TX_CHECKSUM Defined, disables checksum logic on IP packets sent. This is useful in situations in which the underlying network device is capable of generating the IP header checksum, and the application does not use IP fragmentation.
NX_DISABLE_LOOPBACK_INTERFACE Defined, disables NetX support for the loopback interface.
NX_DISABLE_RX_SIZE_CHECKING Defined, disables the size checking on received packets.
NX_ENABLE_IP_STATIC_ROUTING Defined, enables IP static routing in which a destination address can be assigned a specific next hop address. By default IP static routing is disabled.
NX_IP_PERIODIC_RATE Defined, specifies the number of ThreadX timer ticks in one second. The default value is derived from the ThreadX symbol TX_TIMER_TICKS_PER_SECOND, which by default is set to 100 (10ms timer). Applications shall exercise caution when modifying this value, as the rest of the NetX modules derive timing information from NX_IP_PERIODIC_RATE.*
NX_IP_ROUTING_TABLE_SIZE Defined, sets the maximum number of entries in the IP static routing table, which is a list of an outgoing interface and the next hop
addresses for a given destination address. The default value is 8 and is defined in nx_api.h. This symbol is used only if NX_ENABLE_IP_STATIC_ROUTING is defined.

Packet Configuration Options

Option Description
NX_DISABLE_PACKET_INFO Defined, disables packet pool information gathering.
NX_PACKET_HEADER_PAD Defined, enables padding towards the end of the NX_PACKET control block. The number of ULONG words to pad is defined by NX_PACKET_HEADER_PAD_SIZE.
NX_PACKET_HEADER_PAD_SIZE Sets the number of ULONG words to be padded to the NX_PACKET structure, allowing the packet payload area to start at the desired
alignment. This feature is useful when receive buffer descriptors point directly into NX_PACKET payload area, and the network interface receive logic or the cache operation logic expects the buffer starting address to meet certain alignment requirements. This value becomes valid only when NX_PACKET_HEADER_PAD is defined.

RARP Configuration Options

Option Description
NX_DISABLE_RARP_INFO Defined, disables RARP information gathering.

TCP Configuration Options

Option Description
NX_DISABLE_RESET_DISCONNECT Defined, disables the reset processing during disconnect when the timeout value supplied is specified as NX_NO_WAIT.
NX_DISABLE_TCP_INFO Defined, disables TCP information gathering.
NX_DISABLE_TCP_RX_CHECKSUM Defined, disables checksum logic on received TCP packets. This is only useful in situations in which the link-layer has reliable checksum or CRC processing, or the interface driver is able to verify the TCP checksum in hardware.
NX_DISABLE_TCP_TX_CHECKSUM Defined, disables checksum logic for sending TCP packets. This is only useful in situations in which the receiving network node has the received TCP checksum logic disabled or the underlying network driver is capable of generating the TCP checksum.
NX_ENABLE_TCP_KEEPALIVE Defined, enables the optional TCP keepalive timer. The default settings is not enabled.
NX_ENABLE_TCP_MSS_CHECKING Defined, enables the verification of minimum peer MSS before accepting a TCP connection. To use this feature, the symbol NX_ENABLE_TCP_MSS_MINIMUM must be defined. By default, this option is not enabled.
NX_ENABLE_TCP_WINDOW_SCALING Enables the window scaling option for TCP applications. If defined, the window scaling option is negotiated during the TCP connection phase, and the application is able to specify a window size larger than 64K. The default setting is not enabled (not defined).
NX_MAX_LISTEN_REQUESTS Specifies the maximum number of server listen requests. The default value is 10 and is defined in nx_api.h. The application can override the default by defining the value before nx_api.h is included.
NX_TCP_ACK_EVERY_N_PACKETS Specifies the number of TCP packets to receive before sending an ACK. Note if NX_TCP_IMMEDIATE_ACK is enabled but NX_TCP_ACK_EVERY_N_PACKETS is not, this value is automatically set to 1 for backward compatibility.
NX_TCP_ACK_TIMER_RATE Specifies how the number of system ticks (NX_IP_PERIODIC_RATE) is divided to calculate the timer rate for the TCP delayed ACK processing. The default value is 5, which represents 200ms, and is defined in nx_tcp.h. The application can override the default by defining the value before including nx_api.h.
NX_TCP_ENABLE_KEEPALIVE Renamed to NX_ENABLE_TCP_KEEPALIVE. Although it is still being supported, new designs are encouraged to use NX_ENABLE_TCP_KEEPALIVE.
NX_TCP_ENABLE_WINDOW_SCALING Renamed to NX_ENABLE_TCP_WINDOW_SCALING. Although it is still being supported, new designs are encouraged to use NX_ENABLE_TCP_WINDOW_SCALING.
NX_TCP_FAST_TIMER_RATE Specifies how the number of NetX internal ticks (NX_IP_PERIODIC_RATE) is divided to calculate the fast TCP timer rate. The fast TCP timer is used to drive the various TCP timers, including the delayed ACK timer. The default value is 10, which represents 100ms assuming the ThreadX timer is running at 10ms. This value is defined in nx_tcp.h. The application can override the default by defining the value before including nx_api.h.
NX_TCP_IMMEDIATE_ACK Defined, enables the optional TCP immediate ACK response processing. Defining this symbol is equivalent to defining NX_TCP_ACK_EVERY_N_PACKETS to be 1.
NX_TCP_KEEPALIVE_INITIAL Specifies the number of seconds of inactivity before the keepalive timer activates. The default value is 7200, which represents 2 hours, and is defined in nx_tcp.h. The application can override the default by defining the value before including nx_api.h.
NX_TCP_KEEPALIVE_RETRIES Specifies how many keepalive retries are allowed before the connection is deemed broken. The default value is 10, which represents 10 retries, and is defined in nx_tcp.h. The application can override the default by defining the value before nx_api.h is included.
NX_TCP_KEEPALIVE_RETRY Specifies the number of seconds between retries of the keepalive timer assuming the other side of the connection is not responding. The default value is 75, which represents 75 seconds between retries, and is defined in nx_tcp.h. The application can override the default by defining the value before nx_api.h is included.
NX_TCP_MAX_OUT_OF_ORDER_PACKETS Symbol that defines the maximum number of out-of-order TCP packets that can be kept in the TCP socket receive queue. This symbol can be used to limit the number of packets queued in the TCP receive socket, preventing the packet pool from being starved. By default this symbol is not defined, thus there is no limit on the number of out of order packets being queued in the TCP socket.
NX_TCP_MAXIMUM_RETRIES Specifies how many data transmit retries are allowed before the connection is deemed broken. The default value is 10, which represents 10 retries, and is defined in nx_tcp.h. The application can override the default by defining the value before including nx_api.h.
NX_TCP_MAXIMUM_TX_QUEUE Specifies the maximum depth of the TCP transmit queue before TCP send requests are suspended or rejected. The default value is 20, which means that a maximum of 20 packets can be in the transmit queue at any given time. Note packets stay in the transmit queue until an ACK that covers some or all of the packet data is received from the other side of the connection. This constant is defined in nx_tcp.h. The application can override the default by defining the value before it includes nx_api.h.
X_TCP_MSS_CHECKING_ENABLED Renamed to NX_ENABLE_TCP_MSS_CHECKING. Although it is still being supported, new designs are encouraged to use NX_ENABLE_TCP_MSS_CHECKING.
NX_TCP_MSS_MINIMUM Symbol that defines the minimal MSS value NetX TCP module accepts. This feature is enabled by NX_ENABLE_TCP_MSS_CHECK
NX_TCP_RETRY_SHIFT Specifies how the retransmit timeout period changes between retries. If this value is 0, the initial retransmit timeout is the same as subsequent retransmit timeouts. If this value is 1, each successive retransmit is twice as long. If this value is 2, each subsequent retransmit timeout is four times as long. The default value is 0 and is defined in nx_tcp.h. The application can override the default by defining the value before including nx_api.h.
NX_TCP_TRANSMIT_TIMER_RATE Specifies how the number of system ticks NX_IP_PERIODIC_RATE) is divided to calculate the timer rate for the TCP transmit retry processing. The default value is 1, which represents 1 second, and is defined in nx_tcp.h. The application can override the default by defining the value before it includes nx_api.h.

UDP Configuration Options

Option Description
NX_DISABLE_UDP_INFO Defined, disables UDP information gathering.
NX_DISABLE_UDP_RX_CHECKSUM Defined, disables the UDP checksum computation on incoming UDP packets. This is useful if the network interface driver is able to verify UDP header checksum in hardware, and the application does not enable IP fragmentation logic.
NX_DISABLE_UDP_TX_CHECKSUM Defined, disables the UDP checksum computation on outgoing UDP packets. This is useful if the network interface driver is able to compute UDP header checksum and insert the value in the IP head before transmitting the data, and the application does not enable IP fragmentation logic.

NetX Version ID

The current version of NetX is available to both the user and the application software during runtime. The programmer can obtain the NetX version from the nx_port.h file. In addition, this file contains a version history of the corresponding port. Application software can obtain the NetX version by examining the global string _nx_version_id in nx_port.h.

Application software can also obtain release information from the constants shown below, which are defined in nx_api.h.

These constants identify the current product release by name and the product major and minor version.

#define EL_PRODUCT_NETX

#define NETX_MAJOR_VERSION

#define NETX_MINOR_VERSION