NOTE: By default, IP forwarding is turned on. This is typical for a router. If you want a host only product, you could turn off IP forwarding. To do this, remove the IP_DO_FORWARDING flag from the IP_FLAGS_DFLT configuration parameter.

ARP_MAX_ENTRIES -- limit size of ARP table

INCLUDE_TCP -- include the TCP protocol

INCLUDE_UDP -- include the UDP protocol

INCLUDE_ICMP -- include the ICMP protocol

INCLUDE_IGMP -- include the IGMP protocol (host side)

INCLUDE_IGMP_ROUTER -- include the IGMP protocol (router side)

INCLUDE_PING -- include PING client

INCLUDE_SM_NET -- include shared memory network support

INCLUDE_PROXY_SERVER -- include the proxy ARP server

INCLUDE_PROXY_CLIENT -- include the proxy ARP client

INCLUDE_SM_SEQ_ADDR -- assign sequential addresses to hosts on the shared memory back plane

INCLUDE_PROXY_DEFAULT_ADDR -- use default IP address (ead plus 1) for interface to shared memory backplane

SM_OFF_BOARD -- identifies whether shared memory is off or on local board

TCP_FLAGS_DFLT -- TCP Default Flags

TCP_SND_SIZE_DFLT -- TCP Send Buffer Size

TCP_RCV_SIZE_DFLT -- TCP Receive Buffer Size

TCP_CON_TIMEO_DFLT -- TCP Connection Time out

TCP_REXMT_THLD_DFLT -- TCP Retransmission Threshold

TCP_MSS_DFLT -- Default TCP Maximum Segment Size

TCP_RND_TRIP_DFLT -- Default Round Trip Interval

TCP_IDLE_TIMEO_DFLT -- TCP Idle Time-out Value

TCP_MAX_PROBE_DFLT -- TCP Probe Limit

UDP_FLAGS_DFLT -- UDP Configuration Flags

UDP_SND_SIZE_DFLT -- UDP Send Buffer Size

UDP_RCV_SIZE_DFLT -- UDP Receive Buffer Size

ICMP_FLAGS_DFLT -- ICMP Configuration Flags

IP_FLAGS_DFLT -- IP Configuration Flags

IP_MAX_UNITS -- maximum number of interfaces attached to IP layer

IP_TTL_DFLT -- IP Time-to-live Value

IP_QLEN_DFLT -- IP Packet Queue Size

IP_FRAG_TTL_DFLT -- IP Time-to-live Value for packet fragments

NUM_64 -- Number of 64 byte clusters for network data memory pool

NUM_128 -- Number of 128 byte clusters for network data memory pool

NUM_256 -- Number of 256 byte clusters for network data memory pool

NUM_512 -- Number of 512 byte clusters for network data memory pool

NUM_1024 -- Number of 1024 byte clusters for network data memory pool

NUM_2048 -- Number of 2048 byte clusters for network data memory pool

NUM_CL_BLKS -- Number of clBlks for network data memory pool

NUM_NET_MBLKS -- Number of mBlks for network data memory pool

NUM_SYS_64 -- Number of 64 byte clusters for network system memory pool

NUM_SYS_128 -- Number of 128 byte clusters for network system memory pool

NUM_SYS_256 -- Number of 256 byte clusters for network system memory pool

NUM_SYS_512 -- Number of 512 byte clusters for network system memory pool

NUM_SYS_CL_BLKS -- Number of clBlks for network system memory pool

NUM_SYS_MBLKS -- Number of mBlks for network system memory pool

ead -- boot line parameter specifying IP address and mask for boot interface

bootDev -- boot line parameter specifying name of boot network interface

unitNum -- boot line parameter specifying number of boot network interface

gad -- address and mask of the intermediate gateway to host supplying boot image

bad -- address and mask assigned to interface representing the shared memory back plane. If you are using sequential addressing and proxy default addressing, the target generates a bad value from the ead parameter and the CPU number.

igmpRouterLibInit( ) -- initialize IGMPv2 router

igmpRouterLibQuit( ) -- shut down IGMPv2 router

igmpInterfaceEnable( ) -- enable IGMPv2 on specified interface

igmpInterfaceDisable( ) -- disable IGMPv2 on specified interface

igmpLibInit( ) -- initialize the IGMPv2 host

ipAttach( ) -- attach IP to the MUX

ipDetach( ) -- detach IP from the MUX

ifMaskSet( ) -- set network mask for an interface

ifAddrSet( ) -- set IP address for an interface and associated broadcast address

ifBroadcastSet( ) -- set custom broadcast IP address

mRouteAdd( ) -- add a static route to the routing table

mRouteDelete( ) -- delete a static route from the routing table

mRouteEntryAdd( ) -- add a protocol-owned route to the routing table

mRouteEntryDelete( ) -- delete a protocol-owned route from the routing table

proxyPortFwdOn( ) -- allow forwarding of broadcasts for specified port

proxyPortFwdOff( ) -- block forwarding of broadcasts for specified port

smNetShow( ) -- find the shared memory anchor

sysBusToLocalAddr( ) -- get the correct bus address for the shared memory anchor

UDP provides a simple datagram-based end-to-end communication mechanism. UDP extends the message address to include a port address in addition to the host Internet address. The port address identifies one of several distinct destinations within a single host. Thus, UDP accepts messages addressed to a particular port on a particular host, and tries to deliver them, using IP to transport the messages between the hosts. Like IP, UDP makes no guarantees that messages are delivered correctly or even delivered at all.

However, this relatively low-overhead delivery mechanism makes UDP useful to many other protocols and utilities, such as BOOTP, DHCP, DNS, RIP, SNMP, and NFS.

TCP provides reliable, flow-controlled, two-way, process-to-process transmission of data. TCP is a connection-based communication mechanism. This means that before data can be exchanged over TCP, the two communicating processes must first establish a connection through a distinct connection phase. Data is then sent and received as a byte stream at both ends.

Like UDP, TCP extends the connection address to include a port address in addition to the host Internet address. That is, a connection is established between a particular port in one host and a particular port in another host. TCP guarantees that the delivery of data is correct, in the proper order, and without duplication.

ICMP provides information on the success of data transfer. This protocol defines a set of messages that the TCP/IP stack uses to detect a variety of transmission failure types as well as time information. How the TCP/IP stack processes these messages and how these messages change TCP/IP stack configuration often depends upon higher level protocols, such as TCP and interested users of UDP. Still, ICMP is fundamental to monitoring transmission success.

The TCP/IP stack uses IGMP to support multicasting. The standard VxWorks stack supports both the host-side and the router-side of the IGMP v2 protocol.

IGMP v2 is specified in RFC 2236. According to the RFC, IGMP routers listen on enabled interfaces for membership reports from attached hosts. Using this information, the IGMP routers maintain lists of the multicast addresses to which the IGMP hosts are listening. The IGMP router keeps separate lists for each interface. To discover when it needs to prune entries from a list, the IGMP router periodically transmits queries to the multicast groups on a given interface. If no reply arrives within a specifiable time or if a leave message is processed, the IGMP router removes that group from the list for that interface.

To configure the host-side VxWorks IGMP implementation, you need only include it in your image. It starts up automatically at boot time and requires no system management attention. Configuring the router-side implementation can be as simple, although you have more options. For more information, see 4.6 IGMP under VxWorks, p.71.

Table 4-1 :   Network Configuration Options   

	WARNING: Failure to configure these two pools correctly is one of the single biggest causes of "frozen" network applications. The default settings for these pools are just enough to get the stack up, running, and able to respond to simple tests, such as ping. Deployed applications require more resources. Therefore, study carefully the information in Determining Memory Pool Usage, p.55.

The memory in these pools is organized and managed using mBlk structures, clBlk structures, cluster buffers (simple character arrays), and routines supplied by netBufLib. The mBlk and clBlk structures provide information necessary to support buffer sharing and buffer chaining for the data that is stored in clusters. The clusters come in sizes that are determined by the CL_DESC table that describes the memory pool. The netBufLib functions provide an interface that you can use to get or return buffers associated with a memory pool.

The CL_DESC tables for the network system memory pool and the network data memory pool are defined in target/config/comps/src/net/usrNetLib.c as sysClDescTbl[ ] and clDescTbl[ ] respectively.

Valid cluster sizes are powers of two to up to 64KB (65536). Whether a particular cluster size is valid within a particular memory pool depends on the contents of the CL_DESC table that describes the pool. The two pools integral to the network stack use the CL_DESC tables, clDescTbl[ ] and sysClDescTbl[ ].

• Data pool cluster sizes

Data pool cluster sizes are defined in usrNetLib.c by clDescTbl[ ] as follows:

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} 
            };

• System pool cluster sizes

System pool cluster sizes are defined in usrNetLib.c by sysClDescTbl[ ] as follows:

CL_DESC sysClDescTbl [] = 
    { 
    /* 
    clusterSize         num             memArea         memSize 
    -----------         ----            -------         ------- 
    */ 
    {64,                NUM_SYS_64,     NULL,           0}, 
    {128,               NUM_SYS_128,    NULL,           0}, 
    {256,               NUM_SYS_256,    NULL,           0}, 
    {512,               NUM_SYS_512,    NULL,           0}, 
    };

A value in the first column specifies a valid cluster size in bytes. A value in the second column, the "num" column, specifies how many clusters of the specified size are allocated for the table. In the tables shown above, all values in the second column are specified using symbolic constants. You can assign the values of these constants using the standard Tornado configuration utility. In particular, look for these values in the configuration component for network buffer initialization.

If you do not modify the network stack internals, you should not need to edit (add or delete rows) either of these tables directly. However, you will need to adjust the values assigned to the NUM_* constants. See Setting the Number of Clusters on p. 53.

The clBlk provides the first level of abstraction above the data in a cluster. For each cluster in a memory pool, there needs to be a corresponding clBlk structure. Contained in the clBlk is information such as a pointer to the cluster data, the cluster size, and an external reference count.

Above the clBlk, is the mBlk structure. This structure stores a link to a clBlk and can store a link to another mBlk. By chaining mBlks, you can reference an arbitrarily large amount of data, such as a packet chain (see Figure 4-1).

Figure 4-1 :   Presentation of Two Packets in One mBlk Chain

Figure 4-2 :   Different mBlks Can Share the Same Cluster

	WARNING: Failure to configure these two pools correctly is one of the single biggest causes of "frozen" network applications. The default settings for these pools are just enough to get the stack up, running, and able to respond to simple tests, such as ping. Deployed applications require more resources. Therefore, study carefully the information provided in Determining Memory Pool Usage, p.55.

Table 4-2 :   Configuration Parameters for Network Data Memory Pool   

Table 4-3 :   Configuration Parameters for Network System Memory Pool   

Estimating the demands on the network stack memory pools requires a detailed understanding of the applications making the demands. Based on that understanding, you should be able to estimate the number of simultaneous open socket connections, the number of routing table and ARP entries needed, and the number of network interfaces needed. Each of these elements creates a predictable demand on the memory pool. For example:

• TCP socket:.

128 byte cluster, a 256 byte cluster, and a 512 byte cluster; these are used for the generic protocol control block, the TCP protocol control block, and the socket structure respectively. ¹

• UDP socket:.

one 128-byte cluster and one 512-byte cluster; these are used for the generic protocol control block and socket structures.

• Routing table entries:.

four 64-byte clusters and two 256-byte clusters

• ARP cache:.

two 64-byte clusters and one 256-byte cluster per cache entry. To limit the size of the ARP cache, use ARP_MAX_ENTRIES.

• Network interface instance:.

two 64-byte clusters, two 128-byte clusters, and one 256-byte cluster

However, if you are unsure of how your application uses the above resources, you can run the application under the debugger, pause it at critical points, and then compare network stack pool usage at each point. To determine memory pool usage, use the following functions:

netStackSysPoolShow( )

Show network stack system pool statistics.

netStackDataPoolShow( )

Show network stack data pool statistics.

memShow( )

Show blocks and statistics for the current heap partition.

By scaling such single-event values according to your knowledge of how your application uses sockets, the routing table, and so on, you should be able to make some initial estimates on how to set the NUM_* parameters (Table 4-2 and Table 4-3). However, it is critical that you test these values before deploying the system. Failure to adequately reserve memory resources for the network stack is one of the biggest reasons for "frozen" network applications. In addition, you must avoid creating a network stack that reserves nearly all available memory to itself and thus locks out all other applications.

The four-layer model mentioned above describes the data plane functionality of a TCP/IP stack. The data plane describes how the TCP/IP stack organizes the flow of data from an application, down through the stack, out onto the network, and then back. As packets flow down the stack, each layer adds a header to the packet and pushes the packet down to the next level. As packets flow up the stack, each layer strips its header, uses the header to determine the recipient of the packet, and pushes the packet up to the appropriate recipient in the next higher layer.

To deliver a packet, IP hands the packet to the link layer after a routing table lookup determines that the packet is deliverable. If the routing table cannot match the destination address, IP considers the packet undeliverable and discards it. A matching routing table entry gives IP all the information needed to transmit the packet to a destination on the local network.

If the packet is destined for a remote host, the routing table match provides access information for a local gateway. Gateways (also known as routers) have multiple network interfaces (at least two) that let the gateway transfer data between different networks. When a gateway accepts a packet, its IP layer checks the destination of the packet. If the packet is not destined for the gateway itself, IP does a routing table search on the destination address of the packet.

This lookup duplicates the process that took place on the machine originating the packet. Depending on the results of the routing table search, the packet is dropped, delivered, or forwarded. If the packet is forwarded, the process continues until the packet is delivered, dropped, or expired. A packet expires if it cannot reach its destination within a configurable number of hops (gateway forwardings).

If the packet expires, or IP drops the packet, IP generates an ICMP error message. IP uses its data plane functionality to transmit this message, but the message itself is processed by the TCP/IP control plane functionality.

The control plane functionality of the TCP/IP stack allows the protocols to detect transmission failures and the like.

How you set up and manage a routing table for your VxWorks stack depends on your application. For example, you could use RIP to initialize, populate, and manage the routing table. RIP uses IP functionality (through UDP) to announce its presence on the network and discover peers with which to exchange information on network topology.

In addition to a routing protocol, VxWorks includes functionality that you can use to set up and manage a routing table manually. Although you might not use this manual functionality in your deployed application, it is often very useful when you are first developing and debugging your network communications for your application.

Before Classless Inter-domain Routing (CIDR), the Internet address space was divided into address classes (see Figure 4-3), each with its own default network mask (see Table 4-4). IP could determine the class of an address by reading the high-order bits of an Internet address as shown in Figure 4-3.

Figure 4-3 :   Pre-CIDR Internet Address Classes

Table 4-4 :   Pre-CIDR Internet Address Ranges and Masks   

	NOTE: The number of hosts on an IP network is not quite as large as its IP address space. This is because IP requires each network to reserve at least one address as the broadcast address. If the network is divided into subnets, each subnet must similarly reserve a local IP address for broadcasting to the local subnet. By default, VxWorks reserves at least two addresses for broadcasting. One reserved address follows the current convention for broadcast addresses--all host address bit are set. The other reserved address follows the obsolete "all host address bits are cleared" convention. In addition, the ifBroadcastSet( ) routine lets you designate still another address as the local broadcast address.

Under CIDR, IP routing no longer assumes a network mask based on the Internet address class. Although, if you fail to set a network mask value for a network interface before calling ifAddrSet( ), the VxWorks routing table software assumes a default value based on the class system.

In the current CIDR environment, your network is still described by a network number and a mask. However, the mask no longer falls on byte boundaries. Masks can now be assigned by the bit. When choosing a network number, you can select a network mask that has enough bits to include as many IP addresses as you expect to need for your network.

For example, if you need a network of 1000 IP addresses, you would need a netmask of at least 10 bits. Such a mask would give you an address space of 210 addresses (1024 possible IP addresses).

When adding a host or router to an existing network, use the same network mask as all the other interfaces attached to that network. If you did not set up that network, you can get the network mask by asking the network administrator. The network administrator can also assign you an available IP address for the host you are adding.

For a simple example of how you would use masks to divide an address space into subnets, consider a network with the network number 147.38.1.0 and a mask of 24 bits, which you can represent as 255.255.255.0 or 0xFFFFFF00. This gives you an address space of 256 IP addresses (147.38.1.00 through 147.38.1.255).

If you want to divide this space into four equal subnets, you typically need five interfaces, one connecting to the outside world and four connecting to the internal subnets.

To subdivide your address space, you extend the assigned network mask. Each added bit of mask subdivides your address space by powers of two. Thus, if you extend the mask by one bit, you divide your address space into two subnets, two bits subdivides your address space into four subnets, three bits into eight subnets, four bits into 16 subnets, and so on.

If you extend the assigned mask by two bits, the last field of the mask contains a value of:

11 00 00 00 = 27 + 26 + 0  + 0  + 0  + 0  + 0  + 0  = 192 = 0xC0

Joining this to the network mask assigned to your overall network gives you the mask to use on each of the four subnets:

255.255.255.192 = 0xFFFFFFC0

The network number of each subnet is the assigned network number plus all the values expressible within the mask extension:

00 00 00 00 = 0  + 0  + 0  + 0  + 0  + 0  + 0  + 0  =   0 =  0x0 
01 00 00 00 = 0  + 26 + 0  + 0  + 0  + 0  + 0  + 0  =  64 = 0x10 
10 00 00 00 = 27 + 0  + 0  + 0  + 0  + 0  + 0  + 0  = 128 = 0x80 
11 00 00 00 = 27 + 26 + 0  + 0  + 0  + 0  + 0  + 0  = 192 = 0xC0

This gives the four network numbers shown in Table 4-5.

Table 4-5 :   Example Two-Bit Subnets under 147.38.1.00/0xFFFFFF00   

	NOTE: Although the example divides the network into subnets of equal size, it is possible to create subnets of different sizes. For example, the address/mask values 147.38.1.128/0xFFFFFF00, 147.38.1.0/0xFFFFFFC0, and 147.38.1.64/0xFFFFFFC0 create three subnets. The subnets with the longer 0xFFFFFFC0 masks create subnets for the address ranges 147.38.1.0 to 147.38.63 and 147.38.1.64 to 147.38.127. With these subnets already carved out of the 147.38.1.0 to 147.38.1.255 address space, the 147.38.1.128/0xFFFFFF00 subnet contains the 147.38.128 to 147.38.255 space.

	NOTE: Before calling ifAddrSet( ), call ifMaskSet( ) to set the network mask. Otherwise, the network interface assumes the default netmask from the now obsolete class-based system. Such a mask will likely be too large. This is not necessarily a disaster, but the routing table may incorrectly indicate that it has local access to addresses that actually reside on a remote network. For that reason, you will see a lot of ARP errors and transmission failures.

For example, to assign the Internet address 147.38.1.64 to the ln0 interface, enter:

ifAddrSet ("ln0", "147.38.1.64");

The ifAddrSet( ) routine does not let you specify a mask value. Prior to calling ifAddrSet( ), you must set the subnet mask for the interface by calling ifMaskSet( ).

A call to ifAddrSet( ) automatically creates a local entry in the routing table. Local entries in the routing table identify network interfaces on the local host. If you did not assign the correct address to the interface or if you forgot to call ifMaskSet( ) before calling ifAddrSet( ), you need to delete the local host table entry and then reconfigure the interface. The sequence should be:

mRouteDelete ( "old IP address for network interface", "old mask value for network" ) 
ifMaskSet ( "new IP address for network interface", "new mask value for network" )  
ifAddrSet ( "new IP address for network interface", "new mask value for network" )

The IP address for a network interface can be any available IP address within the IP address space of the network to which the interface connects.

A free address is any address not already used by another interface or a service, such as broadcasting. By convention, the broadcast address is the local address with all its host bits set. Thus, within 147.38.1.64/0xFFFFFFC0, the conventional broadcast address is 147.38.1.127:

         Mask: 01 00 00 00 = 0  + 26 + 0  + 0  + 0  + 0  + 0  + 0  =  64 = 0x10 
    Broadcast: 01 11 11 11 = 0  + 26 + 25 + 24 + 23 + 22 + 21 + 20 = 127 = 0x7F

An old-style broadcast address would be 147.38.1.64. When VxWorks on a subnet sees a packet addressed to either address style, it treats it as a broadcast packet for the local network. Beyond avoiding the broadcast address, there are no general conventions for assigning IP addresses. However, many organizations have their own conventions. For example, some organizations reserve the network address plus one as the address of the gateway machine.

	NOTE: You may need to increase the value of the configuration parameter IP_MAX_UNITS.

To start additional network interfaces manually at run-time:

1. Use ifShow( ) to display information on each currently loaded interface. When adding a new interface, you do not want to conflict with any interface already loaded.

1. Use muxDevLoad( ) to load the driver for the network interface.

1. Use muxAddrResFuncAdd( ) to install an address resolution function if necessary. If you loaded an Ethernet driver, you can probably skip this step. Drivers that register as Ethernet drivers automatically use arpresolve( ) to handle address resolution, so you need not call muxAddrResFuncAdd( ).

1. Use muxDevStart( ) to initialize the network interface.

1. Call the network layer's fooAttach( ) routine to attach the driver to the service. For example, to attach to the standard VxWorks stack, call ipAttach( ).

1. Configure the interface. If working with the standard VxWorks stack, this means assigning an IP address and a netmask. Use:

• ifMaskSet( ) -- assign a netmask to the interface

• ifAddrSet( ) -- assign an IP address to the interface

1. Use hostAdd( ) -- to add the interface to the host table.

1. Check that the interface was loaded and configured correctly:

• ifShow( ) -- list configuration information for network devices

• routeShow( ) -- check that the routing table has an entry for the device

• hostShow( ) -- check that the device was added to the host table

	NOTE: For information on the exact inputs expected by the routines named above, see the relevant reference entries.

Consider Figure 4-4. The device acts as a router for tama. When tama pings abuna, the packet goes out 136.12.38.11 to 136.12.38.125, from where it is routed out 136.12.117.10 to 136.12.117.12, the network interface to abuna.

	NOTE: An IGMP router necessarily requires that the host device support at least two network interfaces on which IGMP routing is enabled. Simply including IGMP is not enough. Neither is enabling it on only one interface.

Calling igmpRouterLibInit( ) spawns the IGMP router task and does almost everything necessary to initialize (but not start) the router side of the IGMPv2 implementation. A call to igmpRouterLibInit( ) returns OK if successful, or ERROR otherwise, such as when IGMP has already been started. To actually start IGMP routing, you must enable it on at least two host-local interfaces.

Calling igmpRouterLibQuit( ) ends IGMP routing by closing the IGMP socket, deleting the router task, and generally cleaning up. An igmpRouterLibQuit( ) call returns OK if successful, ERROR otherwise, such as when IGMP has not been started.

Calling igmpInterfaceEnable( ) enables IGMP on an interface. A call to igmpInterfaceEnable( ) applies on the router side only. The host side of IGMP does not have a notion of enabled or disabled interfaces. You can call this function for any interface that is capable of receiving multicast packets.

If you use igmpInterfaceEnable( ) to enable more than one interface on a target, IGMP routing occurs. If there are fewer than two enabled interfaces on a target, there is no possibility of multicast routing. This routine is also responsible for populating the appropriate elements of the IGMP control structure.

An igmpInterfaceEnable( ) call returns OK if successful, ERROR otherwise, such as when an interface is not multicast capable.

igmpInterfaceDisable( ) disables IGMP on an interface. If the target supports fewer than two IGMP-enabled interfaces, IGMP on that target stops acting as a router. igmpInterfaceDisable( ) returns OK if successful, ERROR otherwise, such as when the interface was not enabled.

Table 4-6 :   routeLib Routines   

The routeAdd( ), routeDelete( ), and routeNetAdd( ) functions date from the class-based VxWorks routing table implementation. Thus, when they add routes, they use the netmasks assumed by the class-based system. As a result, the routes they add are often disastrously inappropriate. These functions still work as documented, but you should consider them obsolete. Do not use them in any new code. You should also upgrade existing code to use mRouteAdd( ) and mRouteDelete( ) to manage the static routes in your table.

The procedures vary according to your version of Windows and your networking software package. For the details, see the documentation for your system.

A UNIX system can be told explicitly about a gateway in one of two ways: by editing /etc/gateways or by using the route command. When the UNIX route daemon routed is started (usually at boot time), it reads a static routing configuration from /etc/gateways. Each line in /etc/gateways specifies a network gateway in the following format:

net destinationAddr gateway gatewayAddr metric n passive

where n is the hop count from the host system to the destination network (the number of gateways between the host and the destination network) and "passive" indicates the entry is to remain in the routing tables.

For example, consider a system on network 150. The following line in /etc/gateways describes a gateway between networks 150 and 161, with an Internet address 150.12.0.1 on network 150. A hop count (metric) of 1 specifies that the gateway is a direct connection between the two networks:

net 161.27.0.0 gateway 150.12.0.1 metric 1 passive

After editing /etc/gateways, you must kill the route daemon and restart it, because it only reads /etc/gateways when it starts. After the route daemon is running, it is not aware of subsequent changes to the file.

Alternatively, you can use the route command to add routing information explicitly:

# route add destination-network gatewayAddr [metric]

For example, the following command configures the gateway in the same way as the previous example, which used the /etc/gateways file:

# route add net 161.27.0.0 150.12.0.1 1

Note, however, that routes added with this manual method are lost the next time the system boots.

You can confirm that a route is in the routing table by using the UNIX command netstat -r.

The routeLib API provides a number of functions that you can use to add routes to the routing table. Some of these functions are now obsolete and included for backward compatibility only. All new development should use the following routines:

mRouteAdd( )	Add mask-distinguished static routes.
mRouteEntryAdd( )	Add a protocol-specific dynamic route.

As input to these functions, you can specify IP addresses using either dotted decimal notation or host names.

• About Destination IP Addresses and Destination Networks

Using an IP address, you can specify a single interface on the Internet. Using an IP address and a mask, you can specify a group of IP addresses -- a network.

When creating a host entry in your routing table, you specify the destination as a combination of the following values:

• an IP address

• the RTF_HOST flag

When creating a network entry in your routing table, you specify the destination as a combination of the following values:

• an IP address

• a network mask

In the current implementation, a VxWorks routing table entry also stores:

• type of service

• protocol ID

• weight (router stack implementation only)

In the router stack, it is possible for the routing table to store multiple distinct entries to the same destination. Only one of these route entries is externally visible to protocols such as IP. This representative route is chosen based on its assigned weight. The entry with the lowest weight value is used as the representative route.

If you add a route using a function that does not let you specify a weight, type of service, or protocol ID, VxWorks assigns appropriate default values for these route characteristics.

• Inspecting the Routing Table

Before you edit the table, it is generally a good idea to look at what is already there. To inspect the contents of the routing table, use routeShow( ). If a VxWorks host boots through an Ethernet network interface, a typical routeShow( ) call would display the following:⁴

-> routeShow() 
 
ROUTE NET TABLE 
destination      gateway           flags  Refcnt  Use       Interface  
---------------------------------------------------------------------- 
136.12.44.0      136.12.44.165     101    0       0             ei0  
---------------------------------------------------------------------- 
ROUTE HOST TABLE  
destination      gateway           flags  Refcnt  Use       Interface  
---------------------------------------------------------------------- 
127.0.0.1        127.0.0.1         5      1       0             lo0  
---------------------------------------------------------------------- 
value = 77 = 0x4d = 'M'

In the output shown above, the route entry for 136.12.44.0 shows that the flags RTF_CLONING (0x100) and RTF_UP (0x001, signifying that the route is available for use) are set. This route entry is set when the Ethernet network device "ei0" is initialized. This is a network route and the network mask associated with this route is 0xFFFFFF00.

• Using mRouteAdd( ) to Add Static Gateways and the Default Gateway

To use mRouteAdd( ) to add a gateway to your routing table, you need to specify a destination, a gateway, a net mask, and a type of service value for the route. The general format of an mRouteAdd( ) call is as follows:

mRouteAdd ( "destination", "gateway", netmask, type-of-service, flags)

To use mRouteAdd( ) to add a default entry to the routing table:

mRouteAdd ("0.0.0.0", "gatewayAddrs", 0, 0, 0);

If the routing table contains a route to 0.0.0.0, the gateway assigned to 0.0.0.0 serves as the default for any destination for which there is no better match. Note also that the netmask is all zeros.

	NOTE: Although the boot line gad value (if any) automatically adds an entry to your routing table, the gad is not used as a default gateway (the gateway associated with 0.0.0.0). Instead, the gad gateway has a destination value equal to that of the network (IP address and mask) of the remote network connected to the boot host.

For an example of using mRouteAdd( ) to add a gateway to the routing table, consider the vx2 and vx3 VxWorks targets shown in Figure 4-5. Both have network interfaces that link them to network 161.27.0.0:FFFFFF00. Because vx3 also has an interface on network 150.12.0.0:FFFFFF00, it can serve as a gateway linking networks 150.12.0.0:FFFFFF00 and 161.27.0.0:FFFFFF00.

Figure 4-5 :   Configuring vx3 as a Gateway

• Using Masks to Distribute Traffic to the Same Destination IP Address

Unique routing table entries are defined by a destination address, a network mask (or RTF_HOST flag for host routes), and a type of service value -- not simply a destination IP address. For example, consider the network routing table entries created by the calls:

mRouteAdd( "90.0.0.0", "91.0.0.3",   0xFFFFFF00, 0, 0 ); 
mRouteAdd( "90.0.0.0", "91.0.0.254", 0xFFFF0000, 0, 0 );

Both calls specify a destination IP address of 90.0.0.0 but differ in their network mask values. When the routing software searches the routing table, it tries to match a destination IP address with a routing entry based on the stored network address and network mask.

The first mRouteAdd( ) call creates a routing table entry that matches with destination IP addresses 90.0.0.0 through 90.0.0.255. The second mRouteAdd( ) call uses a shorter mask and so matches more entries, 90.0.0.0 through 90.0.255.255. This overlaps the range of the first mRouteAdd( ) call. However, because routing software prefers matches with longer masks, searches for IP addresses within the 90.0.0.0 to 90.0.0.255 range match the 91.0.0.3 interface first.

Thus, these two entries divide the 90.0.0.0:0xFFFFFF00 traffic between 91.0.0.3 and 91.0.0.254. Packets destined to addresses in the 90.0.0.0 through 90.0.0.255 range go to 91.0.0.3. Packets destined to addresses in the 90.0.1.0 through 90.0.255.255 range go to 91.0.0.254.

If you were to delete the 91.0.0.3 route, all its traffic would go out through 91.0.0.254. However, deleting the 91.0.0.254 route would not result in all its traffic going to 91.0.0.3. Only addresses matching 90.0.0.0 within the 0xFFFFFF00 mask can map to the 91.0.0.3 entry. Thus, addresses in the 90.0.1.0 through 90.0.255.255 range are directed to the default gateway (if any) or are discarded as unreachable.

• Using mRouteDelete( ) to Delete a Static Entry in the Routing Table

To delete a static routing table entry, use mRouteDelete( ). For example, to delete an entry with a destination of 161.27.0.51 with a mask of 0xFFFFFF00, a type of service value of 0, and a flags value of RTF_HOST, you would call mRouteDelete( ) as follows:

mRouteDelete( "161.27.0.51", 0xFFFFFF00, 0, RTF_HOST );

The destination IP address as well as the values for network mask, type of service, and flags that you specify in the parameters must match the values for the table entry. Otherwise, the mRouteDelete( ) call fails.

Although dynamic routes are normally added and deleted by a protocol, it is possible to use mRouteEntryAdd( ) to impersonate a protocol when adding a route.

Proxy ARP is described in Request For Comments (RFC) 925 "Multi LAN Address Resolution," and an implementation is discussed in RFC 1027 "Using ARP to Implement Transparent Subnet Gateways." The ARP protocol is described in RFC 826 "Ethernet Address Resolution Protocol: Or converting network protocol addresses to 48-bit Ethernet address for transmission on Ethernet hardware." The implementation of Proxy ARP for VxWorks is based on RFC 925. However, it is a limited subset of that proposal.

A single proxy ARP instance can act as a server or as a client but not both. Thus, configurations such as that in Figure 4-6 are not supported.

Figure 4-6 :   Multi-Tier Configurations CANNOT Be Used with Proxy ARP

In Figure 4-6, the vx3 target is labeled as a Proxy Server. As a simple proxy server, it cannot fulfill all its functions. The vx3 target must function both as a proxy server for vx5 and vx6 and as a proxy client to vx1. To do this, vx3 must run two instances of proxy ARP; you can configure one instance to function as a server for vx5. The other instance should be configured as a proxy client to vx1. Still, use such configurations with extreme caution. Used casually, you risk accidentally creating network circles, broadcast storms, and eternally forwarded ARP requests.

Figure 4-7 :   Broadcast Datagram Forwarding

	NOTE: When using proxy ARP, it is no longer necessary to specify the gateway. Each target on the shared-memory network (except the proxy server) can register itself as a proxy client by specifying the proxy ARP flag, 0x100, in the boot flags instead of specifying the gateway.

1. PING client (configuration parameter: INCLUDE_PING)

1. Shared memory network initialization (INCLUDE_SM_NET)

1. Proxy ARP server (INCLUDE_PROXY_SERVER)

1. Auto address setup (INCLUDE_SM_SEQ_ADDR)--required for default addressing of proxy clients, but required in both client and server

1. Default address for back plane--required only for default addressing

Parameters for proxy ARP sever:

INCLUDE_PROXY_SERVER
SM_OFF_BOARD=FALSE

Parameters for proxy client:

INCLUDE_PROXY_CLIENT
SM_OFF_BOARD=TRUE

Figure 4-8 :   Multi-Tier Example Using Proxy ARP and IP Routing

	NOTE: Substitute the appropriate network boot device for "ln". The correct boot device is given in the output from a boot prompt ? command.

See Troubleshooting, p.38 for information on debugging the shared memory network.

The following routines can be useful in locating the source of routing problems:

ping( )

Starting from vx1, ping other processors in turn to see if you get the expected result. The function returns OK if it reaches the other machine, or ERROR if the connection fails.

smNetShow( )

This routine displays cumulative activity statistics for all attached processors.

arpResolve( )

This function tells you the hardware address for a specified Internet address. This function supercedes the functionality provided by the now obsolete etherAddrResolve( ).

arpShow( )

This routine displays the current Internet-to-Ethernet address mappings in the system ARP table.

arptabShow( )

This routine displays the known Internet-to-Ethernet address mappings in the ARP table

routeShow( )

This routine displays the current routing information contained in the routing table.

ifShow( )

This routine displays the attached network interfaces for debugging and diagnostic purposes.

proxyNetShow( )

This routine displays the proxy networks and their associated clients.

proxyPortShow( )

This routine displays the ports currently enabled.

Figure 4-9 :   Routing Example

Figure 4-10 :   Unnumbered Interface Setup

Table 4-7 :   Network Address Conversion Macros   

The underlying Internet protocol uses the 32-bit Internet addresses of systems on the network. People, however, prefer to use system names that are more meaningful to them. Thus VxWorks and most host development systems maintain their own maps between system names and Internet addresses.

On UNIX systems, /etc/hosts contains the mapping between system names and Internet addresses. Each line consists of an Internet address and the assigned name(s) for that address:

150.12.0.1 vx1

There must be an entry in this file for each UNIX system and for each VxWorks host on the network. For more information on /etc/hosts, see your UNIX system reference entry hosts(5).

On a VxWorks host, call hostAdd( ) to associate system names with Internet addresses. Make one call to hostAdd( ) for each system with which the VxWorks host communicates. For example:

hostAdd ("vx1", "150.12.0.1");

	NOTE: In addition to hostAdd( ), VxWorks also includes DNS. You can use DNS to create and automatically maintain host-name/address associations for a VxWorks host. See 9. DNS and SNTP.

To associate more than one name with an Internet address, hostAdd( ) can be called several times with different host names and the same Internet address. The routine hostShow( ) displays the current system name and Internet address associations. In the following example, 150.12.0.1 is accessible using the names host, myHost, and widget:

-> hostShow  
value = 0 = 0x0

The standard output device displays the following output:

hostname         inet address     aliases 
--------          -----------     ------- 
localhost        127.0.0.1  
host             150.12.0.1  
 
-> hostAdd "myHost", "150.12.0.1" 
value = 0 = 0x0 
-> hostAdd "widget", "150.12.0.1" 
value = 0 = 0x0 
-> hostShow 
value = 0 = 0x0

Now standard output displays the following:⁶

hostname         inet address     aliases 
--------          -----------     ------- 
localhost        127.0.0.1  
vx1             150.12.0.1       myHost widget  
value = 0 = 0x0

The VxWorks startup routine, usrNetInit( ) in usrNetwork.c, automatically adds the name of the host from which the target booted, using the host name specified in the boot parameters.