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:
- Include the nx_api.h file in all application files that use NetX services or data structures.
- Initialize the NetX system by calling nx_system_initialize from the tx_application_define function or an application thread.
- Create an IP instance, enable the Address Resolution Protocol (ARP), if necessary, and any sockets after nx_system_initialize is called.
- 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:
- Determine how much of the sample is running.
- Increase stack sizes in any new application threads.
- Recompile the NetX library with the appropriate debug options listed in the configuration option section.
- Examine the NX_IP structure to see if packets are being sent or received.
- Examine the default packet pool to see if there are available packets.
- Ensure the network driver is supplying ARP and IP packets with its headers on 4-byte boundaries for applications requiring IP connectivity.
- 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