SSF.Net
Class NIC

java.lang.Object
  |
  +--SSF.OS.ProtocolSession
        |
        +--SSF.Net.NIC
All Implemented Interfaces:
com.renesys.raceway.DML.Configurable

public class NIC
extends ProtocolSession

Network Interface Card.

The NIC is a pseudo-protocol driver that resides at the border between the world of the "quasi-operating system" of SSF.OS (where the protocols interact via the push() of ProtocolMessages between ProtocolSessions), and the world of a discrete event simulation (SSF API) which implements external transmission of encapsulated messages over links (characterized by the exchange of PacketEvents in positive elapsed simulation time).

From the point of view of the Host or Router protocol graph, NIC configures and initializes a queue of outgoing ProtocolMessages (a class implementing SSF.Net.packetQueue), and optionally configures and initializes a packet queue monitoring probe (a class implementing SSF.Net.PacketQueueMonitor).

From the point of view of transmission of messages over links, a NIC maintains a pair of SSF channels to the world outside the protocol graph. A PacketEvent that arrives on the IN channel is converted to a ProtocolMessage and without delay pushed up to the protocol who opened the NIC (typically, IP) for demultiplexing to the destination ProtocolSession.

A ProtocolMessage that is pushed down to the NIC from a protocol above it is handed to a queue manager, which is an instance of a class implementing the Java interface SSF.Net.packetQueue. The queue manager will enqueue (or drop) the packet in an implementation-dependent manner; and schedule the packet event transmission on behalf of the NIC. The default packet queue manager is the droptail (FIFO) queue, but the modeler may specify another class implementing SSF.Net.packetQueue in the DML attribute interface.queue.use.

When a NIC is constructed and configured, it has an IP address assigned, but is "down" (e.g., inactive). A NIC is brought "up" by an open() operation invoked by an instance of class link, receiving two arguments: a reference to the protocol configured over the NIC (usually, but not necessarily, IP), and a reference to the link which is being brought up.

In the simplified "quasi-operating system" of SSF.OS, there are only two sources of interrupts: Timer callbacks (see SSF.OS.Timer) and packet arrivals at network interface cards. These 'interrupts' initiate all processing within the protocol graph; the process of servicing an interrupt itself consumes zero simulation time.


Field Summary
protected  ProtocolSession attachedProtocol
          Reference to the ProtocolSession configured over this NIC (generally, but not necessarily, the local IP session).
protected  double BIT_RATE
          Interface hardware bit rate.
protected  long buffersize
          Buffer size.
protected  boolean CHECK_FOR_SYNS
          If true, a flaky NIC will avoid dropping TCP empty ACK packets, to avoid dropping SYN ACKs and FIN ACKs.
protected  boolean COUNT_FLAKY_DROPS
          If true, a flaky NIC count the drops due to flakiness, which will (can) then be collected by the queue monitor and logged.
 double DEFAULT_BIT_RATE
          Default bitrate: 10Mbit/s
 long DEFAULT_BUFFERSIZE
           
 double DEFAULT_DELAY
          Default internal interface latency: 100 microseconds
 double DEFAULT_FLAKINESS
          Default flakiness: 0.0
protected  double DELAY
          Interface internal latency.
protected  double FLAKINESS
          Flake probability.
protected  long flakyDrops
          Number of flaky drops.
protected  RandomDistribution flakyGen
          Flaky drop random generator
protected  long FREQUENCY
          Clock frequency.
 int ID
          Index of this NIC --- must be unique within one host.
protected  boolean ifaceUp
          Flag to indicate that the interface is configured, has been opened, and is ready for service.
 com.renesys.raceway.SSF.inChannel IN
          In-channel on which packets are received.
 int ipAddr
          32-bit integer IP address of this NIC.
 boolean isVirtual
          True if this interface is a virtual interface (handles no packets, has no link layer, serves only to provide an address to loop back to).
 linkLayer link_hw
          Link-layer interface that handles packet delivery
 int maskBits
          Number of significant bits in the network mask of this NIC (prefix lenth).
 com.renesys.raceway.SSF.outChannel OUT
          Out-channel to which packets are written.
 packetQueue queueManager
          Instance of packetQueue for outgoing traffic.
 PacketQueueMonitor queueMonitor
          Instance of PacketQueueMonitor monitoring the queueManager.
 com.renesys.raceway.SSF.process receiver
          SSF process that receives incoming packets, and pushes their contents to the protocol that opened the NIC.
 
Fields inherited from class SSF.OS.ProtocolSession
name, use
 
Constructor Summary
NIC(ProtocolGraph G, int use_id)
          Constructor for a network interface card.
 
Method Summary
 double bitrate()
          Max bits emitted per simulator tick (i.e., frequency-scaled)
 void close(ProtocolSession higher)
          Bring down this NIC.
 void config(com.renesys.raceway.DML.Configuration cfg)
          Configure a network interface card.
 long delay()
          Internal delay time of network interface, in ticks (frequency-scaled)
 void down()
          Force the NIC to go down at runtime - it will drop all packets sent and received.
 boolean drop_flaky(ProtocolMessage msg)
          Test whether should drop packet due to unreliable link.
 void drop(ProtocolMessage dropped)
          Drop a transmitted or received protocol message (because the NIC is down, or because queue overflows, or because the interface is flaky).
 long frequency()
          Interface clock frequency, in "ticks per second" (Hertz)
 void init()
          This method calls init() in the installed packetQueue and packetQueueMonitor implementations.
 java.lang.String interfaceIdentifier()
          Returns a terse interface identification in format "NHI_address IP_address".
 java.lang.String ipAddrString()
          Returns the complete classless address of this NIC, equal to the IP address in a.b.c.d format, followed by a forward slash, followed by the number of significant bits in the netmask.
 boolean isUp()
          Return the value of ifaceUp, the flag indicating that the interface is ready to send and receive IP packets.
 void open(ProtocolSession higher, java.lang.Object request)
          Bring up this NIC.
 boolean push(ProtocolMessage message, ProtocolSession fromSession)
          Process a ProtocolMessage pushed down from above, by handing it off to the queueManager to be written out to the network.
 java.lang.String toString()
          Returns a string tersely describing the interface configuration.
 void up()
          Bring the NIC up at runtime after it was brought down via NIC.down(), and inject an appropriate route into the FIB.
 
Methods inherited from class SSF.OS.ProtocolSession
closed, debugIdentifier, inGraph, opened, pushAfterDelay, pushAfterDelayFailed, setGraph, version
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ID

public int ID
Index of this NIC --- must be unique within one host.


ipAddr

public int ipAddr
32-bit integer IP address of this NIC.


maskBits

public int maskBits
Number of significant bits in the network mask of this NIC (prefix lenth). For example, a NIC in a class C network would have maskBits=24.


isVirtual

public boolean isVirtual
True if this interface is a virtual interface (handles no packets, has no link layer, serves only to provide an address to loop back to).


queueManager

public packetQueue queueManager
Instance of packetQueue for outgoing traffic.


queueMonitor

public PacketQueueMonitor queueMonitor
Instance of PacketQueueMonitor monitoring the queueManager.


attachedProtocol

protected ProtocolSession attachedProtocol
Reference to the ProtocolSession configured over this NIC (generally, but not necessarily, the local IP session).


ifaceUp

protected boolean ifaceUp
Flag to indicate that the interface is configured, has been opened, and is ready for service.


IN

public com.renesys.raceway.SSF.inChannel IN
In-channel on which packets are received.


OUT

public com.renesys.raceway.SSF.outChannel OUT
Out-channel to which packets are written.


link_hw

public linkLayer link_hw
Link-layer interface that handles packet delivery


receiver

public com.renesys.raceway.SSF.process receiver
SSF process that receives incoming packets, and pushes their contents to the protocol that opened the NIC. This is the NIC's only process. Except for callbacks that take place as a result of timer expiration, all packet-handling activity within a ProtocolGraph takes place as a result of, and on the execution stack of, the receiver process of one of its configured NICs.


FREQUENCY

protected long FREQUENCY
Clock frequency. Defines the minimum logical time resolution of the interface. Normally initialized with reference to the global Net.


FLAKINESS

protected double FLAKINESS
Flake probability. Transmitted packets are dropped with the given probability. Default is zero (100% reliable).


DEFAULT_FLAKINESS

public final double DEFAULT_FLAKINESS
Default flakiness: 0.0

See Also:
Constant Field Values

flakyGen

protected RandomDistribution flakyGen
Flaky drop random generator


CHECK_FOR_SYNS

protected boolean CHECK_FOR_SYNS
If true, a flaky NIC will avoid dropping TCP empty ACK packets, to avoid dropping SYN ACKs and FIN ACKs. The intention is to drop only TCP data segment packets.


COUNT_FLAKY_DROPS

protected boolean COUNT_FLAKY_DROPS
If true, a flaky NIC count the drops due to flakiness, which will (can) then be collected by the queue monitor and logged. In addition to (or instead of) buffer drops.


flakyDrops

protected long flakyDrops
Number of flaky drops.


BIT_RATE

protected double BIT_RATE
Interface hardware bit rate. Defines the number of bits per second that the interface can write onto link during a sustained burst.


DEFAULT_BIT_RATE

public final double DEFAULT_BIT_RATE
Default bitrate: 10Mbit/s

See Also:
Constant Field Values

DELAY

protected double DELAY
Interface internal latency. Defines the number of seconds that elapse between the time a message is enqueued and the time it is written out.


DEFAULT_DELAY

public final double DEFAULT_DELAY
Default internal interface latency: 100 microseconds

See Also:
Constant Field Values

buffersize

protected long buffersize
Buffer size. Defines the number of bytes in the transmit buffer of this NIC. Defaults to infinite-buffer.


DEFAULT_BUFFERSIZE

public final long DEFAULT_BUFFERSIZE
See Also:
Constant Field Values
Constructor Detail

NIC

public NIC(ProtocolGraph G,
           int use_id)
    throws ProtocolException
Constructor for a network interface card. The card is 'down' until it is open()ed during link configuration.

Method Detail

ipAddrString

public java.lang.String ipAddrString()
Returns the complete classless address of this NIC, equal to the IP address in a.b.c.d format, followed by a forward slash, followed by the number of significant bits in the netmask.


up

public void up()
Bring the NIC up at runtime after it was brought down via NIC.down(), and inject an appropriate route into the FIB.


down

public void down()
Force the NIC to go down at runtime - it will drop all packets sent and received. All NIC state variables remain unchanged. Update the FIB to reflect the loss of the route.


isUp

public boolean isUp()
Return the value of ifaceUp, the flag indicating that the interface is ready to send and receive IP packets.


frequency

public final long frequency()
Interface clock frequency, in "ticks per second" (Hertz)


drop_flaky

public final boolean drop_flaky(ProtocolMessage msg)
Test whether should drop packet due to unreliable link.


bitrate

public final double bitrate()
Max bits emitted per simulator tick (i.e., frequency-scaled)


delay

public final long delay()
Internal delay time of network interface, in ticks (frequency-scaled)


toString

public java.lang.String toString()
Returns a string tersely describing the interface configuration.

Overrides:
toString in class java.lang.Object

interfaceIdentifier

public java.lang.String interfaceIdentifier()
Returns a terse interface identification in format "NHI_address IP_address".


config

public void config(com.renesys.raceway.DML.Configuration cfg)
            throws com.renesys.raceway.DML.configException
Configure a network interface card. The supported DML attributes are:
  interface [
    id       %I               # Mandatory identification number unique in host, int
    idrange [from %I to %I]   # alternative array notation for identification numbers

    ip       %S               # Optional IP address (String "a.b.c.d/m")

    bitrate  %F               # Output bits per second  (float),
                              # if omitted default bitrate = 10.*1024*1024 = 10Mbs
    latency  %F               # Internal delay in seconds (float),
                              # if omitted default latency = 0.0001 sec.
    virtual  %S               # If "true" construct a virtual interface, true/false,
                              # if omitted virtual is "false".
    flaky [                   # Force packet drops with given probability
       threshold %F           # 0 <= probability <= 1
       distribution [         # see documentation on configuration of 
        ...                   # random generators.
       ]                      # 
       check_for_syns         # if true, don't drop SYN packets.
       count_flaky_drops      # if true, keep a counter of the number of 
                              # packets dropped due to flakiness.
                              #
    ]                         # if "flaky" is omitted, probability = 0.
                              # 
    tcpdump  %S               # Optional tcpdump filename, uses SSF.OS.binaryTcpDump

    queue [ use %S ]          # Use class named in String %S for SSF.Net.packetQueue,
                              # if omitted, the default queue class is SSF.Net.droptailQueue.
    buffer   %I               # Packet queue buffer size in bytes (int) used by packetQueue,
                              # if omitted, default queue size is "infinite".

    monitor [ use %S ]        # Use class named in String %S for the queue monitor, optional.
  ]
 
If the time to send one bit is less than the resolution of the simulation clock (specified by Net.frequency), clock underflow would result, preventing precise determination of the times at which packets should be written, and causing multiple packets to be sent on the wire at "the same" time. This condition therefore throws a configException; to resolve it, reduce the NIC bitrate or increase Net.frequency.

Specified by:
config in interface com.renesys.raceway.DML.Configurable
Overrides:
config in class ProtocolSession
com.renesys.raceway.DML.configException

init

public void init()
          throws ProtocolException
This method calls init() in the installed packetQueue and packetQueueMonitor implementations.

Overrides:
init in class ProtocolSession
ProtocolException

open

public void open(ProtocolSession higher,
                 java.lang.Object request)
          throws ProtocolException
Bring up this NIC. The "request" argument names the link layer interface that will be handling actual packet delivery. To bring up a NIC, its OUT channel is mapped to the IN() channel of the peer (the link hardware takes care of this), and the send/receive processes are initialized.

This method is called by a link object when a link is being brought up. The link can be thought of as the "introducer" that brings NIC and IP together for each interface making up the link. In response to the open() request, the NIC superclass calls opened() on the higher-level protocol, thus completing the handshake.

Overrides:
open in class ProtocolSession
Throws:
ProtocolException - if neither the opening session nor the opened session are contained within a valid protocol graph, or if they are already contained within different protocol graphs, or if the opening session could not be added to the list of open sessions, perhaps because the max session count has been exceeded

close

public void close(ProtocolSession higher)
           throws ProtocolException
Bring down this NIC. Messages that arrive and any messages pending delivery will be dropped.

Overrides:
close in class ProtocolSession
Throws:
ProtocolException - if the closing session could not be removed from the list of open sessions

push

public boolean push(ProtocolMessage message,
                    ProtocolSession fromSession)
Process a ProtocolMessage pushed down from above, by handing it off to the queueManager to be written out to the network.

Specified by:
push in class ProtocolSession

drop

public void drop(ProtocolMessage dropped)
Drop a transmitted or received protocol message (because the NIC is down, or because queue overflows, or because the interface is flaky).