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.