Chapter 2 - Installation and use of Azure RTOS NetX AutoIP

This chapter contains a description of various issues related to installation, setup, and usage of the Azure RTOS NetX AutoIP component.

Product Distribution

AutoIP for NetX is available at https://github.com/azure-rtos/netx. The package includes three source files, one include files, and a PDF file that contains this document, as follows:

  • nx_auto_ip.h: Header file for NetX AutoIP
  • nx_auto_ip.c: C Source file for NetX AutoIP
  • demo_netx_auto_ip.c: C Source file for NetX AutoIP Demo
  • nx_auto_ip.pdf: PDF description of NetX AutoIP

AutoIP Installation

In order to use NetX AutoIP, the entire distribution mentioned previously should be copied to the same directory where NetX is installed. For example, if NetX is installed in the directory "\threadx\arm7\green" then the nx_auto_ip.h, nx_auto_ip.c, and demo_netx_auto_ip.c files should be copied into this directory.

Using AutoIP

Using NetX AutoIP is easy. Basically, the application code must include nx_auto_ip.h after it includes tx_api.h and nx_api.h, in order to use ThreadX and NetX. Once nx_auto_ip.h is included, the application code is then able to make the AutoIP function calls specified later in this guide. The application must also include nx_auto_ip.c in the build process. These files must be compiled in the same manner as other application files and its object form must be linked along with the files of the application. This is all that is required to use NetX AutoIP.

Note

Since AutoIP utilizes NetX ARP services, ARP must be enabled with the nx_arp_enable call prior to using AutoIP.

Small Example System

An example of how easy it is to use NetX AutoIP is described in Figure 1.1, which appears below. In this example, the AutoIP include file nx_auto_ip.h is brought in at line 002. Next, the NetX AutoIP instance is created in "tx_application_define" at line 090. Note that the NetX AutoIP control block "auto_ip_0" was defined previously as a global variable at line 015. After successful creation, an NetX AutoIP is started at line 098. The IP address change callback function processing starts at line 105, which is used to handle subsequent conflicts or possible DHCP address resolution.

Note

The example below assumes the host device is a single-homed device. For a multihomed device, the host application can use the NetX AutoIP service *nx_auto_ip_interface_*set to specify a secondary network interface to probe for an IP address. See the NetX User Guide for more details on setting up multihomed applications. Note further that the host application should use the NetX API nx_status_ip_interface_check to verify AutoIP has obtained an IP address.

Example of AutoIP use with NetX

000 #include "tx_api.h"
001 #include "nx_api.h"
002 #include "nx_auto_ip.h"
003
004 #define         DEMO_STACK_SIZE         4096
005
006 /* Define the ThreadX and NetX object control blocks... */
007
008 TX_THREAD         thread_0;
009 NX_PACKET_POOL    pool_0;
010 NX_IP             ip_0;
011
012
013 /* Define the AUTO IP structures for the IP instance. */
014
015 NX_AUTO_IP         auto_ip_0;
016
017
018 /* Define the counters used in the demo application... */
019
020 ULONG             thread_0_counter;
021 ULONG             address_changes;
022 ULONG             error_counter;
023
024
025 /* Define thread prototypes. */
026
027 void     thread_0_entry(ULONG thread_input);
028 void     ip_address_changed(NX_IP *ip_ptr, VOID *auto_ip_address);
029 void     _nx_ram_network_driver(struct NX_IP_DRIVER_STRUCT *driver_req);
030
031
032 /* Define main entry point. */
033
034 int main()
035 {
036
037     /* Enter the ThreadX kernel. */
038     tx_kernel_enter();
039 }
040
041
042 /* Define what the initial system looks like. */
043
044 void     tx_application_define(void *first_unused_memory)
045 {
046
047 CHAR     *pointer;
048 UINT     status;
049
050
051     /* Setup the working pointer. */
052     pointer = (CHAR *) first_unused_memory;
053
054     /* Create the main thread. */
055     tx_thread_create(&thread_0, "thread 0", thread_0_entry, 0,
056                     pointer, DEMO_STACK_SIZE,
057                     16, 16, 1, TX_AUTO_START);
058
059     pointer = pointer + DEMO_STACK_SIZE;
060
061     /* Initialize the NetX system. */
062     nx_system_initialize();
063
064     /* Create a packet pool. */
065     status = nx_packet_pool_create(&pool_0, "NetX Main Packet Pool", 128,
066                                     pointer, 4096);
067                                     pointer = pointer + 4096;
068
069     if (status)
070         error_counter++;
071
072     /* Create an IP instance. */
073     status = nx_ip_create(&ip_0, "NetX IP Instance 0", IP_ADDRESS(0, 0, 0, 0),
074                             0xFFFFFF00UL, &pool_0, _nx_ram_network_driver,
075                             pointer, 4096, 1);
076                             pointer = pointer + 4096;
077
078     if (status)
079         error_counter++;
080
081     /* Enable ARP and supply ARP cache memory for IP Instance 0. */
082     status = nx_arp_enable(&ip_0, (void *) pointer, 1024);
083     pointer = pointer + 1024;
084
085     /* Check ARP enable status. */
086     if (status)
087         error_counter++;
088
089     /* Create the AutoIP instance for IP Instance 0. */
090     status = nx_auto_ip_create(&auto_ip_0, "AutoIP 0", &ip_0, pointer, 4096, 1);
091     pointer = pointer + 4096;
092
093     /* Check AutoIP create status. */
094     if (status)
095         error_counter++;
096
097     /* Start AutoIP instances. */
098     status = nx_auto_ip_start(&auto_ip_0, 0 /*IP_ADDRESS(169,254,254,255)*/);
099
100     /* Check AutoIP start status. */
101     if (status)
102         error_counter++;
103
104     /* Register an IP address change function for IP Instance 0. */
105     status = nx_ip_address_change_notify(&ip_0, ip_address_changed,
106                                         (void *) &auto_ip_0);
107
108     /* Check IP address change notify status. */
109     if (status)
110         error_counter++;
111     }
112
113
114     /* Define the test thread. */
115
116     void thread_0_entry(ULONG thread_input)
117     {
118
119     UINT      status;
120     ULONG     actual_status;
121
122
123          /* Wait for IP address to be resolved. */
124         do
125         {
126
127             /* Call IP status check routine. */
128             status = nx_ip_status_check(&ip_0, NX_IP_ADDRESS_RESOLVED,
129                                         &actual_status, 10000);
130
131         } while (status != NX_SUCCESS);
132
133         /* Since the IP address is resolved at this point, the application
134         can now fully utilize NetX! */
135
136         while(1)
137         {
138
139
140
141             /* Increment thread 0's counter. */
142             thread_0_counter++;
143
144             /* Sleep... */
145             tx_thread_sleep(10);
146         }
147     }
148
149
150     void ip_address_changed(NX_IP *ip_ptr, VOID *auto_ip_address)
151     {
152
153     ULONG         ip_address;
154     ULONG         network_mask;
155     NX_AUTO_IP    *auto_ip_ptr;
156
157
158     /* Setup pointer to auto IP instance. */
159     auto_ip_ptr = (NX_AUTO_IP *) auto_ip_address;
160
161     /* Pickup the current IP address. */
162     nx_ip_address_get(ip_ptr, &ip_address, &network_mask);
163
164     /* Determine if the IP address has changed back to zero. If so,
165     make sure the AutoIP instance is started. */
166     if (ip_address == 0)
167     {
168
169         /* Get the last AutoIP address for this node. */
170         nx_auto_ip_get_address(auto_ip_ptr, &ip_address);
171
172         /* Start this AutoIP instance. */
173         nx_auto_ip_start(auto_ip_ptr, ip_address);
174     }
175
176     /* Determine if IP address has transitioned to a non local IP address. */
177     else if ((ip_address & 0xFFFF0000UL) != IP_ADDRESS(169, 254, 0, 0))
178     {
179
180         /* Stop the AutoIP processing. */
181         nx_auto_ip_stop(auto_ip_ptr);
182     }
183
184     /* Increment a counter. */
185     address_changes++;
186 }

Configuration Options

There are several configuration options for building NetX AutoIP. Following is a list of all options, where each is described in detail:

  • NX_DISABLE_ERROR_CHECKING: Defined, this option removes the basic AutoIP error checking. It is typically used after the application has been debugged.
  • NX_AUTO_IP_PROBE_WAIT: The number of seconds to wait before sending first probe. By default, this value is defined as 1.
  • NX_AUTO_IP_PROBE_NUM: The number of ARP probes to send. By default, this value is defined as 3.
  • NX_AUTO_IP_PROBE_MIN: The minimum number of seconds to wait between sending probes. By default, this value is defined as 1.
  • NX_AUTO_IP_PROBE_MAX: The maximum number of seconds to wait between sending probes. By default, this value is defined as 2.
  • NX_AUTO_IP_MAX_CONFLICTS: The number of AutoIP conflicts before increasing processing delays. By default, this value is defined as 10.
  • NX_AUTO_IP_RATE_LIMIT_INTERVAL: The number of seconds to extend the wait period when the total number of conflicts is exceeded. By default, this value is defined as 60.
  • NX_AUTO_IP_ANNOUNCE_WAIT: The number of seconds to wait before sending announcement. By default, this value is defined as 2.
  • NX_AUTO_IP_ANNOUNCE_NUM: The number of ARP announces to send. By default, this value is defined as 2.
  • NX_AUTO_IP_ANNOUNCE_INTERVAL: The number of seconds to wait between sending announces. By default, this value is defined as 2.
  • NX_AUTO_IP_DEFEND_INTERVAL: The number of seconds to wait between defense announces. By default, this value is defined as 10.