4.6   Configuring the Network Stack

Changing the default network stack configuration involves setting values for various #define statements. To configure the amount of memory that the network stack uses for the network memory pool, modify the clDescTbl table defined in target/src/config/usrNetwork.c.

4.6.1   Network Protocol Scalability

By default, the build creates a VxWorks image that includes the code implementing the TCP, UDP, ICMP, and IGMP protocols. If you want to exclude one of these protocols, reconfigure VxWorks. The relevant configuration macro is found in the table below:

INCLUDE_TCP

 

Includes the TCP protocol.

 

INCLUDE_UDP

 

Includes the UDP protocol.

 

INCLUDE_ICMP

 

Includes the ICMP protocol.

 

INCLUDE_IGMP

 

Includes the Internet Group Management Protocol (IGMP).

 

4.6.2   Setting #defines for the IP, TCP, UDP, and ICMP Protocols

This section describes the configuration for the network layer protocols. Table 4-3 describes all configuration options. For some options, the default value is specified using symbolic constants. These symbolic constants are defined in netLib.h. To override any default values assigned to these constants, reconfigure VxWorks with the appropriate values set.

Table 4-3:  Network Configuration Options


Configuration Constant
 
Default Value and Description
 

TCP Default Flags
(TCP_FLAGS_DFLT)
 
Default Value: TCP_DO_RFC1323
Includes RFC1323 support. RFC 1323 is a specification to support networks that have high bandwidth and longer round trip times. This option is enabled by default. If this option cannot be negotiated by the peer, it should drop the option. If the host does not understand this option, it terminates the connection. For such hosts, you must turn off this option.
 
TCP Send Buffer Size
(TCP_SND_SIZE_DFLT)
 
Default Value: 8192
Sets the default send buffer size of a TCP connection.
 
TCP Receive Buffer Size
(TCP_RCV_SIZE_DFLT)
 
Default Value: 8192
Sets the default receive buffer size of a TCP connection.
 
TCP Connection Timeout
(TCP_CON_TIMEO_DFLT)
 
Default Value: 150 (75 seconds)
Sets the timeout on establishing a TCP connection.
 
TCP Retransmission Threshold
(TCP_REXMT_THLD_DFLT)
 
Default Value: 3
Sets the number of duplicate ACKs needed to trigger the fast retransmit algorithm. Typically, TCP receives a duplicate ACK only if a segment is lost.
 
Default TCP Maximum Segment Size
(TCP_MSS_DFLT)
 
Default Value: 512
Sets the default maximum segment size to use if TCP cannot establish the maximum segment size of a connection. To establish a maximum segment size, TCP typically uses the maximum transmission unit of the network interface on which the connection is established.
 
Default Round Trip Interval
(TCP_RND_TRIP_DFLT)
 
Default Value: 3 (seconds)
Sets the round-trip time to use if TCP cannot get an estimate within 3 seconds. The round trip time of a connection is calculated dynamically.
 
TCP Idle Timeout Value
(TCP_IDLE_TIMEO_DFLT)
 
Default Value: 14400 (4 hours, in seconds)
Sets the idle time for a connection. Idle times in excess of this value trigger a keep alive probe. After the first keep alive probe, a probe is sent every 75 seconds for a number of times restricted by the TCP Probe Limit.
 
TCP Probe Limit
(TCP_MAX_PROBE_DFLT)
 
Default Value: 8
Sets the maximum number of keep alive probes sent out on an idle TCP connection. TCP drops the connection after sending out the maximum number of keep alive probes.
 
UDP Configuration Flags
(UDP_FLAGS_DFLT)
 
Default Value: UDP_DO_CKSUM_SND | UDP_DO_CKSUM_RCV
Tells UDP to calculate a UDP header and data checksum for both send and receive UDP datagrams.
 
UDP Send Buffer Size
(UDP_SND_SIZE_DFLT)
 
Default Value: 9216
Sets the default send buffer size of a UDP connection.
 
UDP Receive Buffer Size
(UDP_RCV_SIZE_DFLT)
 
Default Value: 41600
Sets the default receive buffer size of a UDP connection.
 
ICMP Configuration Flags
(ICMP_FLAGS_DFLT)
 
Default Value: ICMP_NO_MASK_REPLY
The default value specifies no ICMP mask replies. If this option is enabled on a VxWorks host, and the host receives an ICMP mask query, the VxWorks host replies with its network interface mask.
 
IP Configuration Flags
(IP_FLAGS_DFLT)
 
Default Value: IP_DO_FORWARDING | IP_DO_REDIRECT | IP_DO_CHECKSUM_SND | IP_DO_CHECKSUM_RCV
The default value enables forwarding of packets and enables sending ICMP redirect messages (if it is necessary to redirect packets through a different router). The RFC requires that you send and receive checksums. To prevent sending a checksum, clear the IP_DO_CHECKSUM_SND bit. Likewise, clear IP_DO_CHECKSUM_RCV to prevent a checksum receive.
 
IP Time-to-live Value
(IP_TTL_DFLT)
 
Default Value: 64
Sets the IP default time to live, an upper limit on the number of routers through which a datagram can pass. This value limits the lifetime of a datagram. It is decremented by one by every router that handles the datagram. If a host or router gets a packet whose time to live is zero (this value is stored in a field in the IP header), the datagram is thrown out and the sender is notified with an ICMP message. This prevents packets from wandering in the networks forever.
 
IP Packet Queue Size
(IP_QLEN_DFLT)
 
Default Value: 50
Sets the default length of the IP queue and the network interface queue. IP packets are added to the IP queue when packets are received. Packets are added to the network interface queue when transmitting.
 
IP Time-to-live Value for packet fragments
(IP_FRAG_TTL_DFLT)
 
Default Value: 60 (30 seconds for received fragments)
Sets the default time to live value for an IP fragment. To transmit a packet bigger than the MTU size, the IP layer breaks the packet into fragments. On the receiving side, IP re-assembles these fragments to form the original packet. Upon receiving a fragment, IP adds it to the IP fragment queue. Each fragment waiting to be re-assembled has its own time to live, which, by default, is 30 seconds. This means that a fragment is deleted from the queue if it cannot be assembled in 30 seconds.
If the network is extremely busy, the IP fragment queue can accumulate a lot of fragments that are waiting to be reassembled. This clutter can cause the queue to grow very large and thus take up a lot of system memory. To alleviate this problem, you can reduce the value of this configuration constant.
 

4.6.3   Network Memory Pool Configuration

VxWorks allocates and initializes memory for the network stack only once, at network initialization time. Out of this pre-allocated memory, the network stack uses netBufLib routines to set up a memory pool. From this memory pool, the network stack uses netBufLib routines to get the memory needed for data transfer.

The netBufLib routines deal with data in terms of mBlk structures, clBlk structures, and clusters. The mBlk and clBlk structures provide information necessary to manage the data stored in clusters. The clusters, which come in different sizes, contain the data described by the mBlk and clBlk structures. When VxWorks sets up the network stack memory pool, it needs to know the number of mBlks, clBlks, as well as the number of clusters per cluster size. The default counts are specified by symbolic constants defined in h/netBufLib.h. These constants are described in Table 4-4.


*

CAUTION: Change these constants only after you fully understand what they do. Setting inappropriate values can make the TCP/IP stack inoperable.

Table 4-4:  Configuration Constants for Network Memory Pools


Constant
 
Description
 

Network memory blocks for user data
(NUM_NET_MBLKS)
 
Default value: 400
Specifies the number mBlk structures to initialize. At a minimum, there should be at least as many mBlks as there are clusters.
 
Number of 64 byte clusters for user data
(NUM_64)
 
Default value: 100
Specifies the number of 64-byte clusters to initialize.
 
Number of 128 byte clusters for user data
(NUM_128)
 
Default value: 100
Specifies the number of 128-byte clusters to initialize.
 
Number of 256 byte clusters for user data
(NUM_256)
 
Default value: 40
Specifies the number of 256-byte clusters to initialize.
 
Number of 512 byte clusters for user data
(NUM_512)
 
Default value: 40
Specifies the number of 512-byte clusters to initialize.
 
Number of 1024 byte clusters for user data
(NUM_1024)
 
Default value: 25
Specifies the number of 1024-byte clusters to initialize.
 
Number of 2048 byte clusters for user data
(NUM_2048)
 
Default value: 25
Specifies the number of 2048-byte clusters to initialize.
 
Size of network memory pool for user data
(NUM_CL_BLKS)
 
Default value: NUM_64 + NUM_128 + NUM_256 + NUM_512 + NUM_1024 + NUM_2048
This value specifies the number of clBlk structures to initialize. You need exactly one clBlk structure per cluster. If you add another cluster pool to clDescTbl[ ] (described below), be sure you increment this value appropriately.
 

Default Memory Pool Configuration for the Network Stack

By default, the VxWorks network stack creates six pools (all within the main network memory pool) for clusters ranging in size from 64 bytes to 2048 bytes. However, valid cluster sizes can range from 64 bytes increasing by powers of two to 64K (65535). If your network stack needs clusters of a valid but non-default size, you can edit the clDescTbl table defined in target/src/config/usrNetwork.c. The following is an example and clDescTbl[ ] table:

CL_DESC clDescTbl [] =  /* network cluster pool configuration table */ 
            { 
            /* 
            clusterSize         num             memArea         memSize 
            -----------         ----            -------         ------- 
            */ 
            {64,                NUM_64,         NULL,           0}, 
            {128,               NUM_128,        NULL,           0}, 
            {256,               NUM_256,        NULL,           0}, 
            {512,               NUM_512,        NULL,           0}, 
            {1024,              NUM_1024,       NULL,           0}, 
            {2048,              NUM_2048,       NULL,           0} 
            };

To add a cluster pool for clusters of 4096 bytes each, edit clDescTbl[ ] as follows: 1

CL_DESC clDescTbl [] =  /* network cluster pool configuration table */ 
            { 
            /* 
            clusterSize         num             memArea         memSize 
            -----------         ----            -------         ------- 
            */ 
            {64,                NUM_64,         NULL,           0}, 
            {128,               NUM_128,        NULL,           0}, 
            {256,               NUM_256,        NULL,           0}, 
            {512,               NUM_512,        NULL,           0}, 
            {1024,              NUM_1024,       NULL,           0}, 
            {2048,              NUM_2048,       NULL,           0}, 
            {4096,              NUM_4096,       NULL,           0} 
            };


*

CAUTION: Adjust the counts for mBlks, clBlks, clusters, and cluster pools only after collecting data on system behavior and deciding whether or how you would like to change that behavior. Carefully planned changes can significantly improve performance, but reckless changes can significantly reduce performance.

The values shown above are reasonable defaults, but the network requirements for your system could be radically different. For example, your use of the network stack could require more clusters of a particular size. Making such a determination is a matter of experimentation and analysis. However, as background information, you need to understand how data divides up into mBlks, clBlks, and clusters.

The mBlk structure is the primary vehicle through which you access data in a memory pool established by netPoolInit( ). Because the mBlk structure merely references the data, this lets network layers communicate data without actually having to copy the data. In addition, data can be chained using mBlks. Thus, you can pass an arbitrarily large amount of data by passing the mBlk at the head of an mBlk chain. Consider Figure 4-5

. 2

As shown in Figure 4-5, an mBlk references data only indirectly - through a clBlk structure. This indirection makes it easier for multiple mBlks to share the same cluster. See Figure 4-6

.

Please note that using a clBlk structure instead of a pointer to provide a level of indirection is not an extravagance. The clBlk structure tracks how many mBlks share its underlying cluster. This is critical when it comes time to free an mBlk/clBlk/cluster construct. If you use netMblkClFree( ) to free the construct, the mBlk is freed back to the pool and the reference count in the clBlk is decremented. If the reference count drops to zero, the clBlk and cluster are also freed back to the memory pool.

Configuring Memory Pools Out of Private Memory

The clDescTbl[ ] shown in the previous section did not make use of the memArea and memSize members. For the default network buffer pool, the memory allocation calls are handled internally and the values of memArea and memSize are set for you. However, if necessary, you can supply these values and thus explicitly determine the size and location of the memory pools. For more information on how to use the memArea and memSize members, see the reference entry for netPoolInit( ).

4.6.4   Testing Network Connections

You can use the ping( ) utility from VxWorks to test whether a particular system is accessible over the network. Like the UNIX command of the same name, ping( )sends one or more packets to another system and waits for a response. You can identify the other system either by name or by its numeric Internet address. This is useful for testing routing tables and host tables, or determining whether another machine is responding to network requests.

The following example shows ping( ) output for an unreachable address:

-> ping "150.12.0.1",1 
no answer from 150.12.0.1 
value = -1 = 0xffffffff = _end + 0xfff91c4f

If the first argument uses a host name, ping( ) uses the host table to look it up, as in the following example:

-> ping "caspian",1 
caspian is alive 
value = 0 = 0x0

The numeric argument specifies how many packets to expect back (typically, when an address is reachable, that is also how many packets are sent). If you specify more than one packet, ping( ) displays more elaborate output, including summary statistics. For example, the following test sends packets to a remote network address until it receives ten acknowledgments, and reports on the time it takes to get replies:

-> ping "198.41.0.5",10 
PING 198.41.0.5: 56 data bytes 
64 bytes from 198.41.0.5: icmp_seq=0. time=176. ms 
64 bytes from 198.41.0.5: icmp_seq=1. time=64. ms 
64 bytes from 198.41.0.5: icmp_seq=2. time=64. ms 
64 bytes from 198.41.0.5: icmp_seq=3. time=64. ms 
64 bytes from 198.41.0.5: icmp_seq=4. time=80. ms 
64 bytes from 198.41.0.5: icmp_seq=5. time=64. ms 
64 bytes from 198.41.0.5: icmp_seq=6. time=64. ms 
64 bytes from 198.41.0.5: icmp_seq=7. time=64. ms 
64 bytes from 198.41.0.5: icmp_seq=8. time=64. ms 
64 bytes from 198.41.0.5: icmp_seq=9. time=64. ms 
 
----198.41.0.5 PING Statistics---- 
10 packets transmitted, 10 packets received, 0% packet loss 
round-trip (ms)  min/avg/max = 64/76/176 
value = 0 = 0x0

The report format matches the format used by the UNIX ping utility. Timings are based on the system clock; its resolution could be too coarse to show any elapsed time when communicating with targets on a local network.

Applications can use ping( ) periodically to test whether another network node is available. To support this use, the ping( ) routine returns a STATUS value and accepts a PING_OPT_SILENT flag as a bit in its third argument to suppress printed output, as in the following code fragment:

/* Check whether other system still there */ 
 
if (ping (partnerName, 1, PING_OPT_SILENT) == ERROR) 
    { 
    myShutdown();              /* clean up and exit */ 
    } 
...

You can set one other flag in the third ping( ) argument: PING_OPT_DONTROUTE restricts ping( ) to hosts that are directly connected, without going through a gateway.


1:  For this particular clDescTbl[ ] table only, you can specify memArea values as NULL and memSize values as 0. When the network initialization code actually allocates the necessary memory, it resets these values appropriately. For all other clDescTbl[ ] tables, you must provide these values explicitly before calling netPoolInit( ). For more information, see the reference entry for netPoolInit( ).

2:  To support chaining across multiple packets, the mBlk structure contains two members that
support of chaining. One member points to the next mBlk in the current packet. The other member points to the head mBlk in the next packet (if any).