Part I
The Abstract Network Model (INET)

2 Inside a Node

Fig.2 shows the internal structure of a network node in the abstract network model.  Instead of having four layers in the TCP/IP model or seven layers in the OSI model, we have only two layers in J-Sim: the upper protocol layer (UPL) and the core service layer (CSL). The UPL contains transport, signaling, and application protocol modules. We do not impose a specific structure in this layer so components in this layer may form an arbitrary graph. The CSL provides a set of well-defined services (that are common in most network architectures) to modules in the UPL. In some sense, we encapsulate the network layer, the link layer and the physical layer into one CSL.  The services provided in CSL are described in details in the following section. 

Figure 2: The internal structure of a network node.

3 Core Service Layer and Services

• 3.1 Data Services
• 3.2 Identity Services
• 3.3 Routing Table Services
• 3.4 Interface/Neighbor Services
• 3.5 Multicast Services
• 3.6 Packet Filter Configuration Services
• 3.7 Contract Classes

The core service layer provides a set of well-defined services and events to modules in the upper protocol layer. These services and events are categorized and listed below:

Data services

Send and deliver packets.

Service/Event	Service/Event Description	Port
Packet Sending	Sends packets using one of the following methods: default forward, explicit multicast, exclusive broadcast.	up port group (*@up)
Packet Delivery	Defines the information associated with packet delivery from CSL to an UPL module.
Packet Arrival (Component event)	Is exported when a packet arrives at the CSL (either from local or the network).	.pktarrival@

 

Identity services

Allow UPL modules to query or configure the identities of the node.

Service/Event	Service/Event Description	Port
Default Identity Retrieval	Retrieves the default identity of the node.	.service_id@
All Identities Retrieval	Retrieves all the identities of the node.
Identities Query	Queries if an identity exists.
Identity Addition	Adds identities to the node.
Identity Removal	Removes identities from the node.
Identity Timeout Query	Queries the times when identities expire.
Identity Event (Component event)	Is exported when an ID is added to, or removed from, the node. The event object is an array of identities (long[]) being added or removed.	.id@

 

Routing table services

Allow UPL modules to query or configure the routing table of the node.

Service/Event	Service/Event Description	Port
Unicast Route Query	Is exported when CSL cannot determine the outgoing interfaces on which a unicast packet should be forwarded.	.ucastquery@
Multicast Route Query	Is exported when CSL cannot determine the outgoing interfaces on which a multicast packet should be forwarded.	.mcastquery@
Route Lookup	Looks up the outgoing interfaces for a given combination of source, destination, and incoming interface.	.service_rt@
Route Entry Addition	Adds a route entry to the routing table.
Graft	Grafts a set of outgoing interfaces to an existing route entry.
Prune	Prunes a set of outgoing interfaces from an existing route entry.
Route Entry Removal	Removes route entries from the routing table.
Route Entry Retrieval	Retrieves route entries from the routing table.
Unicast Route Event (Component event)	Is exported when a unicast route is added, modified, or removed.	.rt_ucast@
Multicast Route Event (Component event)	Is exported when a multicast route is added, modified, or removed.	.rt_mcast@

 

Interface/Neighbor services

Allow UPL modules to query the interface/neighbor information of interface(s) of the node.

Service/Event	Service/Event Description	Port
All Interfaces Retrieval	Retrieves information of all existing interfaces.	.service_if@
One Interface Retrieval	Retrieves information of a specific interface.
Neighbor Event (physical) (Component event)	Is exported when a neighbor is discovered on a physical interface of the node.	.if@
Neighbor Event (virtual) (Component event)	Is exported when a neighbor is discovered on a virtual interface of the node.	.vif@

Multicast services

Service/Event	Service/Event Description	Port
Member Join	Same as the identity addition service.	.service_mcast@
Member Leave	Same as the identity removal service.
Member Query	Same as the identities query service.
Multicast Group Event	Is exported when a host joins a new multicast group or the last host leaves a  multicast group.	.mcastHost@

 

Packet filter configuration services

Allow UPL modules to configure the packet filters in the core service layer.

Service/Event	Service/Event Description	Port
Packet Filter Configuration	Configures a packet filter.	.service_configswitch@

Fig.3 illustrates the services provided by CSL and the ports associated with the services. These services are described in detail in the following subsections.

Figure 3: The core service layer, services, events and ports.

3.1 Data Services

Packet Sending Service (downward)

Is used for an UPL module to send a packet to the network. In this service, an UPL module chooses one of the following methods to forward the packet: default forward, explicit multicast, and exclusive broadcast.  In the default forward method, the CSL looks up the routing table based on the specified destination address to determine on which outgoing interface(s) the packet should be sent. In the explicit multicast method, the CSL sends the packet on the interfaces specified.  In the exclusive broadcast method, the CSL sends the packet on all the interfaces except the ones specified. The message format for using this service is as follows:

 

Field	Field Type	Description
Type	int	0: Default forward, 1: explicit multicast, 2: exclusive broadcast.
Packet	Object	The packet to be sent.
Packet Size	int	Size of the packet to be sent.
Source	long	The source address. If not specified, the address drcl.net.Address.NULL_ADDRESS is used.
Destination	long	The destination address.
Router Alert	boolean	The router alert flag.
TTL	int	The time-to-live counter.
ToS	long	The type-of-service field. Bits that are defined in J-Sim are: Bit Description 0 0: data packet, 1: control packet. 1 The ECT (the ECN-capable transport) bit; a value of 1 indicates ECN (Explicit congestion notification)-capable transport at the sender end (based on RFC2481). 2 The CE (congestion experience) bit; a value of 1 indicates congestion along the path (based on RFC2481).
Interfaces	int[]	The set of interfaces. Only for service types 1 and 2.

 

Packet Delivery Service (Upward)

Is used for an UPL module to receive a packet from the network. The format of the message delivered by the CSL is as follows:

Field	Field Type	Description
Packet	Object	The packet to be sent.
Source	long	The source address.
Destination	long	The destination address.
Router Alert	boolean	The router alert flag.
TTL	int	The time-to-live setup.
ToS	long	The type-of-service field. Bits that are defined in J-Sim are: Bit Description 0 0: data packet, 1: control packet. 1 The ECT (the ECN-capable transport) bit; a value of 1 indicates ECN (Explicit congestion notification)-capable transport at the sender end (based on RFC2481). 2 The CE (congestion experience) bit; a value of 1 indicates congestion along the path (based on RFC2481).
Incoming Interface	int	Interface on which the packet arrives.

 

Packet Arrival Event

is a component event and is exported to notify interested modules of arrival of every packet. The object of the event is the arrived packet. Whether the packet is from a local module or from the network can be determined in the event description.

3.2 Identity Services

The CSL of a node maintains a list of identities (or addresses) of this node known by the other nodes in the network. A unicast address is an identity owned by at most one node in the network, while a multicast address is an identity by which more than one node may be identified in the network. An UPL module may look up and/or configure the identities of the node using the following service contracts:

Default Identity Retrieval

The initiator (an UPL module) sends an integer of 0 (drcl.data.IntObj) and the reactor (CSL) responds with the default identity of the node in drcl.data.LongObj.

 

All Identities Retrieval

The initiator (an UPL module) sends an integer of 1 (drcl.data.IntObj) and the reactor (CSL) responds with all the identities of the node in long[].  

 

Identities Query

The initiator (an UPL module) sends an array of identities in question (long[]) and the reactor (CSL) responds with the corresponding array of answers in boolean[]. An answer of true indicates that the node does own the identity.

 

Identity Addition

The initiator (an UPL module) sends a request in  the following format:

Field	Field Type	Description
Command	int	0 (the "add" command).
Identities	long[]	The identities to be added.
Lifetimes	double[]	The lifetimes of the identities to be added.

In response, the reactor adds the set of identities to its database. Each identity remains valid for the time duration specified in the corresponding lifetime and then removed. One may specify a non-positive value or Double.NaN as the lifetime value to indicate that  the corresponding identity remains valid until explicitly removed.

 

Identity Removal

The initiator (an UPL module) sends a request in  the following format:

Field	Field Type	Description
Command	int	1 (the "remove" command).
Identities	long[]	The identities to be removed.

In response, the reactor removes the set of identities from its database.

 

Identity Timeout Query

The initiator (an UPL module) sends a request in  the following format:

Field	Field Type	Description
Command	int	2 (the "query" command).
Identities	long[]	The identities in question.

In response, the reactor sends back the set of time values in double[], each of which corresponds to the remaining lifetime of the corresponding identity.

There are two contract classes, drcl.inet.contract.IDLookup and drcl.inet.contract.IDConfig, available in J-Sim to help create requests, retrieve specific fields from a request, or prepare responses for the above services. See the class APIs for details from the above links.

Identity Events

Whenever there is a change in the identity database, the CSL exports an event at the designated event port (.id@). Two events are defined: identity added and identity removed. The event object in both cases is ether an identity (drcl.data.LongObj) or an array of identities (long[]).

3.3 Routing Table Services

The CSL  maintains a routing table.  For each packet to be forwarded, the CSL looks up the forwarding interfaces in the table, based on the source address, the destination address, and/or the incoming interface on which the packet arrived. An UPL module may look up or configure the routing table using the following routing service contracts:

Route Lookup

The initiator (an UPL module) specifies the source address, the destination address, and the incoming interface on which the packet arrived, in an drcl.inet.data.RTKey object, and sends the key. The reactor (CSL) then responds with the interface(s) (int[]) on which the packet should be forwarded.

 

Route Entry Addition

To add a new, or modify an existing, route entry, the initiator sends a request in  the following format:

Field	Field Type	Description
Command	int	0 (the "add" command).
Key	drcl.inet.data.RTKey	The key of the route entry.
Entry	drcl.inet.data.RTEntry	The route entry to be added.
Lifetime	double	The lifetime of the entry.

Upon receipt of the request, the reactor (CSL) adds (modifies if the entry already exists) the entry to the routing table and keeps the entry for the lifetime specified. The lifetime can be nonpositive or Double.NaN to keep the entry valid until it is explicitly removed. In the case of modifying an existing entry, a zero value of the lifetime enables the reactor to keep the previous lifetime.

 

Graft

The initiator sends a request with the same format as an "add" request except that the first command field is an integer of 1 (the "graft" command). Upon receipt of a "graft" request, the reactor modifies the route entry as if it were an "add" request except that the reactor adds (rather than replaces with) in the entry the outgoing interfaces specified in the request.

 

Prune

The initiator sends a request with the same format as an "add" request except that the first command field is an integer of 2 (the "prune" command). Upon receipt of a "prune" request, the reactor modifies the route entry as if it were an "add" request except that the reactor prunes from the routing entry the outgoing interfaces specified in the request.

 

Route Entry Removal

The initiator sends a request in the following format:

Field	Field Type	Description
Command	int	3 (the "remove" command).
Key	drcl.inet.data.RTKey	The key to match the entry/entries.
Match method	String	The way to find the entries for removal.

 

There are four matching methods: exact, longest, all, wildcard:

Exact match: Two keys are said to be exactly matched if

        key1.value == key2.value && key1.mask == key2.mask.

Before introducing the other three matching methods, we first define the term "matched to."

Match: A key (key1) is said to be matched to another key (key2) if

       (key2.mask & key1.value) == key2.maskedValue ------- Condition (1)

 where key2.maskedValue = key2.mask & key2.value. Note that the mask of key1 is not used.

All match: Finds all the entries to whose keys the given key is matched.

Longest match: Among the "all match" entries, find the entry to whose key the given key is matched for the most number of bits in Condition (1).

Wildcard match: Finds all the entries whose keys are matched to the given key.

EXAMPLE Entries in routing table: Index Value Mask  MaskedValue    0  0000  0000  0000    1  1000  1000  1000    2  0100  1100  0100    3  1100  1100  1100    4  0110  1110  0110    5  1110  1110  1110 Given the key (1111, 1100), no entry is exactly matched. Entries 0, 1, 3, 5 are returned with the "all match" method. Entry 5 is the longest matched entry. Entries 3, 5 are returned with the "wildcard match" method. The wildcard match method is useful when, for example, one would like to retrieve all the entries with the values of their keys starting with "11".

All the entries of the matched keys are removed and returned. In the cases of exact and longest matches, at most one entry is returned in drcl.inet.data.RTEntry. In the other cases, an array of matched entries (drcl.inet.data.RTEntry[]) are returned.

 

Route Entry Retrieval

The format of a retrieval request is the same as a removal except that the first command field is an integer of 4 (the "retrieve" command). The reactor returns all the matched entries in the same manner as it responds to a removal request, except that the matched entries are not removed from the routing table.

 

Unicast/Multicast Route Query

In the cases when the CSL cannot determine the outgoing interfaces on which a packet should be forwarded, the CSL acts as an initiator of the route lookup contract and sends a lookup request at the designated ports. An UPL module that listens to these ports can handle the request by adding the necessary routing entries.  In this manner, an UPL may have a complete control on how packets are forwarded in the CSL.

Special data structures used for these services are drcl.inet.data.RTKey and drcl.inet.data.RTEntry. Both of them have a set of constructors to help create the instances with different combinations of arguments. There are also the contract classes, drcl.inet.contract.RTLookup and drcl.inet.contract.RTConfig, available to help create requests, retrieve specific fields from a request, or prepare replies for the above services. See the class APIs for details from the above links.

Unicast/Multicast Route Events

Whenever there is a change in the routing table, the CSL exports an event at the designated event ports (.rt_ucast@ and .rt_mcast@). Three events are defined: route added, route removed and route modified. In the cases of route added and route removed events, the event object is the route itself. In the case of the route modified event, the event object is an array of two route entries: the old entry followed by the new, updated entry.

3.4 Interface/Neighbor Services

The CSL of a node keeps track of the information of all the interfaces of the node in a data structure called InterfaceInfo. The information of an interface includes the local address (drcl.inet.data.NetAddress), the addresses (drcl.inet.data.NetAddress) of the neighbors that can be reached on the interface, the size of the outgoing buffer, the bandwidth, the maximum transmission unit (MTU) and so on. The CSL provides the following services to retrieve the information and/or to notify interested modules of neighbor events (e.g., the event that a new neighbor is discovered, or the event that an existing neighbor is down).

All Interfaces Retrieval

The initiator sends a null request and the reactor returns an array of interfaces in drcl.inet.data.InterfaceInfo[], each element of which corresponds to an interface of the node.

 

One Interface Retrieval

The initiator sends an interface index in drcl.data.IntObj and the reactor returns the information of the interface in drcl.inet.data.InterfaceInfo; or null if the interface does not exist.

 

Neighbor Events

Is exported when a new neighbor is discovered (the neighbor up event) or an existing neighbor is down (the neighbor down event). Both neighbor events share the same event object of the following format:

 

Field	Field Type	Description
Interface index	int	Index of the interface on which the neighbor can be reached.
Neighbor address	drcl.inet.data.NetAddress	The network address of the neighbor.

The CSL further distinguishes the cases whether the neighbor can be reached on a physical interface or a virtual interface. In the first case, the events are exported through the .if@ port, while in the second case, the .vif@ port.

The neighboring information may be manually, statically configured into the CSL. In this case, the CSL exports all the neighbor-up events at the node boot-up time. Alternatively, the CSL may be instrumented to build the neighbor information and export the neighbor events dynamically (by running some generic Hello protocol). 

3.5 Multicast Services

The CSL provides the multicast group join/leave/query services at an end host for multicast applications to join/leave/query a multicast group. The contracts for these services are identical to the identity addition/removal/query services.

In addition, the CSL in a router may export the multicast group events to a multicast routing protocol whenever appropriate. The event message is in the following format:

3.6 Packet Filter Configuration Services

Packet filters are conceptually the extensible part of the CSL. Each interface of a node may contain a bank of packet filters. When the CSL forwards a packet on an outgoing interface, the packet may traverse a subset of packet filters in the bank before being placed in the outgoing buffer of the interface. When a packet arrives on an interface of a node, it may also traverse a (possibly different) subset of packet filters in the bank before being handed to the dispatching function of the CSL. While different implementations of CSL may have different sets of packet filters installed, all implementations should provide the following service for UPL modules to configure packet filters:

Packet Filter Configuration

The initiator sends a request in the following format:

Field	Field Type	Description
Filter bank index (or interface index)	int	Index of the filter bank or interface.
Filter index	int	Index of the packet filter in the bank.
Request	Object	The configuration request.

Upon receipt of the request, CSL dispatches the request to the packet filter specified, and then returns a reply if applicable. The contents of the request and the reply depend on the actual function and implementation of the packet filter, and are not specified in this document.

3.7 Contract Class

The drcl.inet package includes a set of contract classes, under drcl.inet.contract, to help create service requests, retrieve data fields from service replies, and/or execute contracts.  A UPL module writer could save time if he makes good use of these contract classes. The following table lists all the contract classes available and the services supported by them.

To better understand how the contract classes simplify the programmer's job, we examine the methods defined in drcl.inet.contract.IDLookup below:

public class IDLookup extends Contract
{
	public static long getDefaultID(Port out_);
	public static long[] getAllIDs(Port out_);
	public static boolean query(long id_, Port out_);
	public static boolean[] query(long[] ids_, Port out_);

	public static Object createGetDefaultRequest();
	public static Object createGetAllRequest();
	public static Object createQueryRequest(long id_);
	public static Object createQueryRequest(long[] id_)
}

For example, the getDefaultID(Port) method executes the "Default Identity Retrieval" contract and returns the result, the default identity of the node. The port in the argument is where the contract takes place at the initiator side. For another example, the createGetDefaultRequest() returns the request for the "Default Identity Retrieval" service.

4 Decomposition of the Core Service Layer

The abstract network model does not specify how the CSL should be structured and implemented. One may have different CSL implementations for simulating network nodes at different levels of details.  However, for the purpose of better code reuse and extendibility, the drcl.inet package includes a default CSL implementation. The CSL component in this implementation is a composite component that consists of several sub-components. Each of the sub-components is responsible for one or more CSL services and events.

The default CSL implementation, the relations among its sub-components, and the services/events exported by these sub-components are illustrated in Fig.4 (which shows the CSL of a router with two interfaces):

Figure 4: The decomposition of the CSL.

NOTE: Since J-Sim v1.2, the default CSL composition combines the queue and network interface into one QueueNI component.

The sub-components are implemented and placed under drcl.inet.core. The sub-components, their functions and the services and events they are responsible for are listed in the following table.

where <i> is the packet filter bank/interface index and <j> is the index of the packet filter in the bank.  These sub-components can be quickly referenced in Part IV, Quick Reference of INET Classes.

One can use these components to build  nodes. For example, Fig.5 depicts a typical host node with only one interface, one packet dispatcher and one identity component in the CSL component.

Figure 5: A typical host node.

Fig.6 depicts a router with two interfaces. In this router, both OSPF and DVMRP use the identity lookup service (from id) and the routing table configuration services (from rt).  Also, DVMRP listens to the multicast route query event (from pd) and IGMP uses the identity configuration services (from id).

Figure 6: A simple two-interface router.

Fig.7 depicts the possible structure of a border router with three interfaces, one of which is the border interface of the domain. On this interface is equipped a policer (as a packet filter) which monitors incoming traffic from a different domain. In addition to OSPF and DVMRP, it also runs BGP for inter-domain routing and RSVP for inter-domain signaling. RSVP uses the packet filter configuration service to configure the policer and the packet scheduler on q2. It also uses the route lookup service and listens to route change events.

Figure 7: A possible border router.