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).