cnet   (local)UNIX Programmer's Manual   cnet(local)

NAME

cnet - a communications network simulation program

SYNOPSIS

cnet [many options] {TOPOLOGY_FILE | -r nnodes}

DESCRIPTION

cnet is a program which enables experimentation with various data-link layer, network layer, routing and transport layer networking protocols. In addition, different application and physical layers may be provided which exhibit varying statistical characteristics of message generation and data transmission.

cnet first accepts a number of command line options and then either reads from a network topologyfile (described later) or generates a random network. Having built and checked the network topology, cnet will compile and dynamically link any source files specified on the command line or those files containing the implementation of the protocols for each network node. Each node will execute its own copy of the network protocols (as specified in either ANSI-C code or ``old'' K&R C). In particular, each node has its own set of variables and will execute unique instances of event- handling functions when interesting network events occur. Each node is initially rebooted by calling its specific reboot_node() function. Thereafter, each node is expected to register event-handling functions to be invoked by the cnet round-robin scheduler when interesting events occur.

cnet either displays the entire network on a window under XView or Motif or runs rather less visually on an ASCII terminal. Under X-windows, nodes may be re-positioned and selected using the left mouse button. Selecting a node results in a sub-window being displayed which contains the output and statistics panels of that node. The node's attributes of message rates and sizes may be modified while the network is running by selecting choice buttons. Similarly, the default attributes of all nodes in the network may be simultaneously modified by selecting the default node panel from the bottom panel and then changing the node attributes thereon. Selecting a node with the right mouse button displays a menu from which the node may be forced to reboot, (impolitely) crash, (politely) shutdown and reboot, pause and (hardware) fail.

Selecting a link using the left mouse button results in a sub-window being displayed which contains the statistics panel for that link. Links are bidirectional, so ``selecting a link'' means clicking on the link near the end of its source. The link-based attributes of costs and probabilities of error may be modified while the network is running by dragging slider panels. Similarly, the attributes of all links in the network may be simultaneously modified by first selecting the default link panel from the bottom panel and then changing the link attributes thereon.

The current node and link attributes (as possibly modified via the windowing interface) are available to each node in C data structures and variables declared in . These are initialized when each node is rebooted and updated as each node is scheduled for execution. The contents of these data structures should be considered as readonly values and not be modified directly by the protocols. They may be successfully modified via the windowing interface.

COMMAND-LINE OPTIONS

cnet supports a number of options which should be presented before the name of the topology file or a request for a random topology.

-A string

Specify a "compilation string" which declares a new application layer to be used (see COMPILATION STRINGS). If -A is not provided, a default (internal) application layer is used. The eventual application layer is used as the source and sink of all messages.

-c
Normally the time_of_day clocks in each node are initially different (and protocols could be developed to synchronize the clocks). If -c is specified, the clocks in all nodes will initially be synchronized.

-C string
Specify a "compilation string" which declares each node's "internal" layers to be used (see COMPILATION STRINGS). If -C is not provided, the string "protocol.c" is assumed.

-d
Provide some diagnostic/monitoring information while cnet is running.

-e
Normally, corruption errors on links are not reported by the Physical Layer and must be detected by the receiver. If -e is specified, function read_physical() will detect and report corruption errors by returning -1 and setting cnet_errno to ER_CORRUPTDATA.

-E nevents
Request that cnet only run for the indicated number of events.

-f secs
Set the frequency (in seconds) of the diagnostic and statistical summary. In combination with -s and -z, cumulative statistics may be periodically reported.

-F filename
If cnet has been compiled for TclTk, the indicated file will be sourced by the Tcl interpreter. If the file cannot be found directly, CNETPATH will be search to locate the file.

-g
Commence execution (go) as soon as the main window appears (under X-windows); implied by -X.

-k
Use ``old'' Kernighan and Ritchie (K&R) C to compile the user supplied source files for the application layer (-A, the ``central'' protocol layers (-C), and the physical layer (-P). The default is to use the ANSI-C compiler, gcc.

-L
Normally, an attempt to write to a link that has failed appears to succeed. Protocols must detect this error as they do for frame loss. The -L option enables writes on failed links to be observed by returning -1 and setting cnet_errno to ER_LINKFAILURE.

-m mins
To prevent runaway processes (and students) choking our teaching machines, a 3 minute time limit is silently imposed on cnet execution. The -m option overrides this limit.

-M mins
Limit the length of the simulation to -M minutes of 'simulated time' when used in combination with -T.

-n
Simply parse the topology file, compile and link all necessary C source files and then exit.

-N
Provide the number of nodes in the network in the C variable NNODES. Surprisingly, the default is that each node does not know how many nodes the network con- tains (NNODES = 0).

-o file_prefix
Copy the output of each node's printf(), puts() and putchar() to a file with the indicated prefix. For example, the use of -o output will typically create and write to the files output.node0, output.node1, output.node2, ....

-O
Open all node windows on startup (unless overridden by the winopen attribute).

-p
After building and checking the network topology, simply print it out and exit cnet.

-P string
Specify a "compilation string" which declares a new physical layer to be used (see COMPILATION STRINGS). If -P is not provided, a default (internal) physical layer is used. The eventual physical layer is used to deliver and possibly corrupt and lose data frames.

-q
Execute quietly (and more quickly) - all output requested with printf(), puts() and putchar() will not appear in the output windows. All output produced dur- ing an EV_DEBUG? event (a button press) will still appear, as will all output ``mirrored'' in logging files.

-r nnodes
Request that a random network be generated, consisting of nnodes. Each node will have at least one link but the whole network is not (yet) guaranteed to be con- nected. The -r option may be used instead of providing a topology file.

-R function_name
Use function_name() as the function to first invoke when rebooting each node. By default, the function reboot_node() will be invoked.

-s
Print a summary of the network's activity just before cnet exits.

-S seed
Provide the seed for random number generation (for mes- sage generation and frame corruption).

-t
Trace all events delivered to each network node. A description of all cnet function calls, arguments and return and cnet_errno values is reported via standard error. Any output requested with CNET_trace will also appear on standard error.

-T
By default, cnet runs in ``wall-clock'' time, that is, the simulation performs one second of network-work in one second of ``wall-clock'' time. This works well for up to about 20 nodes beyond which cnet ``gets behind''. Using -T forces cnet to ignore the ``wall-clock'' time and to execute as a true discrete-event simulator.

-v
Be very verbose reporting cnet's actions.

-X
Disable support for X-windows (the default for ASCII terminals!).

-z
Display statistics and event summaries even if they are zero (implies -s).

Specifying all of -M mins, -S seed and -T enables a simulation to be replayed.

NETWORK TOPOLOGIES

Each point-to-point network consists of a number of nodes in a (not necessarily fully) connected graph. The nodes may be either hosts or routers. Host nodes have an application layer which is responsible for the generation and receipt of messages to and from other hosts. Routers have no application layer but are otherwise identical to hosts. All nodes have a number of attributes that may be specified in the topology file and, in the case of hosts, the application layer message sizes and delivery rates may be modified under X-windows. Using a combination of node attributes (specified in the topology file) mouse and menu selections under X-windows, nodes may be forced to reboot, (impolitely) crash, (politely) shutdown, pause and (hardware) fail.

The links between nodes are unreliable, being subject to noise bursts and possible corruption and loss of data frames. The rates of reliability together with the propagation delay along links may be controlled with link attributes in the topology file or under X-windows. Links are connected to nodes via transmission buffers whose maximum size may similarly be controlled. Links may also have costs (weights) ascribed to them for each frame and byte transmitted.

All information about the network is described in a network topology file, an example of which follows.

        probframecorrupt = 4,  probframeloss  = 3,
        minmessagesize   = 1k, maxmessagesize = 4k
        compile          = "protocol.c",

        host perth {
            x=100, y=200,
            link to melbourne { costperframe = 8 }
        }
        host melbourne {
            x=270, y=200
            link to sydney    { costperframe = 1, propagationdelay = 10ms },
            link to hobart    { costperframe = 6 }
        }
        host brisbane {
            x=430, y=100
            link to sydney    { costperframe = 3 }
        }
        host hobart {
            x=400, y=300
            link to sydney    { costperframe = 5 },
            link to melbourne { costperframe = 3 }
        }
        host sydney {
            x=470, y=200
            link to hobart    { costperframe = 4 }
        }

By default, every node in the network only knows its own node and link characteristics and the number of direct links it has to its neighbours. Unless the -N option is provided (or a constant hard-coded in C), each node is even unaware of how many nodes exist in the network. All other informa- tion must be derived by each node using its network proto- cols.

NETWORK ATTRIBUTES

A number of node and link attributes may be specified in the topology file to define and constrain the network. Node or link attributes that are defined in the topology file before all node specifications become the default, or global, attributes for all following nodes and links. Different attributes for individual nodes and links may thereafter be defined locally to override the default attributes. Under X-windows, node and link attributes that may be modified while the network is running are presented on choice buttons and slider panels. Choice buttons whose description is ``Default'' and slider panels whose value is -1 indicate that the value of that attribute is taken from those of the default node or default link. The default node and link attributes may be seen and modified by selecting their panels with the bottom panel buttons.

Attributes which define probabilities are expressed as one chance in a power of two of the event occurring. For exam- ple, a probframecorrupt of 4 indicates that there is one in sixteen (uniform distribution) chance of a data frame being corrupted on a link. Attributes which define times or rates must be appended with either 's' or 'ms' to scale their values. For example, a propagationdelay expressed as 500ms indicates a delay of half a second. Attributes which define sizes in bytes may be followed by the letter k to represent multiplication of that size by 1024; for example 4k represents 4096 bytes.

Node attributes:

        x, y            - integer coordinates of the node's icon on the
		                  topology canvas.
        winx, winy      - absolute integer coordinates of the
                          node's window under X-windows.
        winopen         - boolean attribute requesting that a
                          node's window be opened on startup.
        address         - the network address of each node.
        outputfile      - the name of the output file for each
                          node.  When used as a global attribute,
                          outputfile is used as a filename prefix
                          (as with the -o option).  When used
                          locally, outputfile indicates the com-
                          plete filename.
        rebootnode      - the name of the ANSI-C function to call
                          when each node reboots (locally over-
                          rides the -R option).
        compile         - a compilation string to declare the
                          sourcefile names containing the proto-
                          cols for each node (locally overrides
                          the -C option).
        messagerate     - the rate at which the application layer
                          can generate new messages for delivery.
        minmessagesize  - the minimum size (in bytes) of messages
                          generated by the application layer.
        maxmessagesize  - the maximum size (in bytes) of messages
                          generated by the application layer.
        nodemtbf        - the expected rate at which the node
                          will fail due to a hardware failure.
        noderepairtime  - the expected time taken to repair a
                          hardware failure.
        trace           - a boolean indicating if event tracing
                          is required (overrides the -t option).

Link attributes:

        bandwidth       - the bandwidth along a link (in bits per
                          second).
        propagationdelay- the propagation delay along a link (in
                          milliseconds).
        probframecorrupt- the probability that a frame on this
                          link will be corrupted.
        probframeloss   - the probability that a frame on this
                          link will be lost altogether.
        costperbyte     - the cost (in cents) per byte along this
                          link.
        costperframe    - the cost (in cents) per frame along
                          this link.

Note that all links are bidirectional - there is a link Sydney -> Melbourne although this is not explicitly declared. Unless otherwise indicated, traffic costs are the same in both directions - the cost of Sydney -> Melbourne is 1c per frame, but the Sydney -> Hobart costs are different in each direction. Note also that the total cost of sending a frame from Melbourne to Hobart is cheaper if directed via Sydney.

COMPILATION STRINGS

Strings are used to declare the location (filename) of the shared object codes for the application, ``central'' and physical layers used in the simulation. These strings may be provided on the command line, via the -A, -C and -P options, or via the compile node attribute in the topology file.

In their simplest form, compilation strings may present just a single C sourcefile name, such as "protocol.c". If neces- sary, cnet, will compile the file protocol.c into the object file protocol.o and then link this file to form the final shared object protocol.cnet. This final shared object file will then be used to provide the code for each node's relevant layer(s).

In its more complex form, a compilation string may also include compilation switches, a number of sourcefile names, and linker switches. For example, the compilation string "-DDEBUG ftp.c tables.c -lm" includes a compilation (actually preprocessor) switch which is passed onto the compilation process, two sourcefile names and a linker switch (in this case to link with the mathematics library). Each source file is compiled (if necessary) to create its object file, and all object files are then linked together to form a single shared object. The shared object's name is derived from the first sourcefile found, in this case it will be ftp.cnet. The switches -l and -L are recognized as linker switches, all other switches are assumed to be compilation switches.

cnet performs the rudimentary actions of make(3), compiling and linking files if the required target does not exist or is out-of-date with respect to sourcefiles.

NETWORK LIBRARY FUNCTIONS

cnet employs an event-driven programming style to indicate to each node that events associated with the network need attention. Events occur when a node reboots, when the application layer has a message for delivery, when the physical layer has received a frame on one of its links, when a line of input is available from the node's stdio window, when a software timer expires, when one of the five debugging buttons is selected from the node's window and when a node is being (politely) shutdown. No event is delivered if a node pauses, crashes or suffers a hardware failure.

Event-handling functions must be registered to receive incoming events. The only exception to this is that the function reboot_node() is assumed to be the function to invoke on node reboots (unless overridden with either the -R option or the rebootnode attribute). Each handler is invoked with three parameters - the event causing the invocation, a timestamp and a user-defined data value. The timestamp has significance for functions handling timer events; all other handlers will simply receive the special NULLTIMESTAMP. Notice that timestamps do not reflect the current time; they specify which timer has expired. The user-defined data value is initially provided as the third parameter to CNET_set_handler() which will ensure that the same data value is passed to the handler. The user-defined data value for timeout handlers is also presented as the third parameter to CNET_start_timer().

The following network library functions, presented here as ANSI-C prototypes, are supported by cnet. Their use, calling conventions and parameters are similar, though not identical, to those used in Tanenbaum's ``Computer Networks'', 2nd edition.

Application layer functions:

The application layer (either the internal default version or one provided with the -A option) has the responsibility of generating messages to be delivered to other application layers. An application layer will not generate a message for its own node. Notice that the required destination node is identified by its network address and not node number. Each node's address and node number will in fact be the same, unless the address attribute is specified in the topology file. The default application layer prefers to generate messages for ``close nodes'', with a message having twice the chance of being for an immediate neighbour as for a node two hops away (and so on).

     int CNET_read_application(CnetAddr *dest,char *msg,int *len);

On invocation, len must point to an integer indicating the maximum number of bytes that may be copied into msg. On return, len will point to an integer now indi- cating the number of bytes copied into msg. The net- work address of the required destination node is copied into destaddr.

     int CNET_write_application(char *msg, int *len);

Passes a number of bytes, pointed to by msg, ``up to'' the application layer. On invocation, len must point to an integer indicating the number of bytes to be taken from msg. On return, len will point to an integer now indicating the number of bytes accepted by the application layer.

     void CNET_enable_application(CnetAddr destaddr);

Permits the application layer to generate messages to the node with the indicated network address. If the destaddr is the symbolic constant ALLNODES, message generation to all nodes will be enabled. Initially, message generation to all destination nodes is disabled and must be enabled to begin the generation of mes- sages.

     void CNET_disable_application(CnetAddr destaddr);

Prevents the application layer from generating new mes- sages to the node with the indicated network address. If the destaddr is the symbolic constant ALLNODES, mes- sage generation to all nodes will be disabled. This function should be called when a harried node runs out of buffer space, or perhaps while routing information is being gathered.

Physical layer functions:
The physical layer (either the internal default version or one provided with the -P option) has the responsibility of delivering data frames between nodes. Frames are delivered along links, numbered within each node from 1 to the number of links. Link 0 is provided to copy a frame immediately from a node's output to input. In general, the physical layer will randomly corrupt and drop data frames on all links other than 0.

     int CNET_write_physical(int link, char *frame, int *len);

Passes a number of bytes, pointed to by frame ``down to'' the physical layer which will attempt to deliver them on the indicated link (wire). Each node has a fixed number of links, the first available link is number 1, the second is number 2, and so on. As a spe- cial case, a node may reliable transmit a frame to itself by requesting the LOOPBACK(=0) link. On invoca- tion, len must point to an integer indicating the number of bytes to be taken from frame. On return, len will point to an integer now indicating the number of bytes accepted by the physical layer.

     int CNET_write_physical_reliable(int link,char *frame,int *len);

Identical to CNET_write_physical() though the transmis- sion is guaranteed to be error free (providing a reli- able data-link layer).

     int CNET_write_direct(CnetAddr destaddr, char *msg, int *len);

Similar to CNET_write_physical_reliable() but the network address of the required destination node may be specified (providing a reliable network/routing layer for asynchronous message passing). Messages transmit- ted using CNET_write_direct() are considered to be transmitted on, and arrive on, link number 1. The spe- cial destination address BROADCAST may be used to transmit a message to all nodes except the sender.

     int CNET_read_physical(int *link, char *frame, int *len);

Accepts the specified maximum number of bytes from the physical layer, placing them in the address pointed to by frame. On invocation, len must point to an integer indicating the maximum number of bytes that may be copied into frame. On return, len will point to an integer now indicating the number of bytes taken from the physical layer and link will point to an integer indicating on which link they were received.

Timer functions:
A total of 10 software timer queues are supported to provide a call-back mechanism for user code. For example, when a data frame is transmitted a timer is typically created which will expire sometime after that frame's acknowledgement is expected. Timers are referenced via unique integers termed timestamps. When a timer expires, the event handler for the corresponding event is invoked with the event and unique timestamp as parameters. Timers may be cancelled to prevent them expiring (for example, if the acknowledgement frame arrives before the timer expires). Timers are automatically cancelled as a result of their handler being invoked.

     CnetTimestamp CNET_start_timer(CnetEvent ev, long msec, CnetData data);

Requests that a new timer be created which will expire in the indicated number of milliseconds. One of the ten timer queues may be requested by passing one of the event types EV_TIMER1..EV_TIMER10. A unique timestamp is returned to distinguish this newly created timer from all others. This timestamp should later be used in subsequent calls to CNET_stop_timer(). If a new timer cannot be created, the special timestamp NULLTIMESTAMP will be returned.

     int CNET_stop_timer(CnetTimestamp ts);

Requests that the indicated timer be cancelled (before it has expired).

Other functions:

     int CNET_set_handler(CnetEvent ev, void (*func)(), CnetData data);

Register func as the void ``returning'' function to be invoked when the event ev occurs.

     int CNET_read_keyboard(char *line, int *len);

Requests the specified maximum number of bytes from the keyboard buffer placing them in the address pointed to by line. On invocation, len will point to an integer indicating the maximum number of bytes that may be copied into line. On return, line will be NULL-byte terminated (and not include a newline) and the integer pointed to by len will contain strlen(line)+1.

     int CNET_set_debug_string(CnetEvent ev, char *str);

Change the string on the indicated X-windows debug but- ton (for EV_DEBUG1..EV_DEBUG5) to str. If str is NULL or the empty string, the indicated button is removed.

     int CNET_set_time_of_day(long newsec, long newms);

Change the node's notion of the wall-clock time of day. As nodeinfo should be considered a read-only structure, this is the only method to set time_of_day.sec and time_of_day.ms . (time_of_day.sec is the number of seconds since Jan. 1, 1970, and may be used in a call to ctime(3c)).

     int  CNET_set_cursor(int  row, int  col);

     int  CNET_get_cursor(int *row, int *col);
	 
     void CNET_clear_to_eoln(void), CNET_clear_to_eos(void);

Under X-windows, functions to move the cursor of each node's output window to the indicated row and column (home is (0,0)), clear to the end of the screen and to the end of the current line.

     int checksum_internet(unsigned short *addr, int nbytes);

     unsigned short checksum_ccitt(unsigned char * addr, int nbytes);

     unsigned short checksum_crc16(unsigned char * addr, int nbytes);

     unsigned int   checksum_crc32(unsigned char * addr, int nbytes);

Functions which take a memory address and perform the specified checksum calculation on the indicated number of bytes starting from that address.

     int  CNET_trace(const char *, ...);

If tracing is requested (globally, or for certain nodes) this printf()-like function will produce its output on the stderr stream.

Function restrictions:
Note that calls to the functions CNET_write_application(), CNET_read_application(), CNET_enable_application(), CNET_disable_application() and CNET_set_handler(EV_APPLICATIONLAYER,...) or CNET_set_handler(EV_KEYBOARDREADY,...) are only valid if called from a host node.

Function calls to either the application or physical layers are invalid when cnet is not running (this can occur under X-windows when the simulation is paused and a node's debug button is selected).

OUTPUT AND ERROR HANDLING

All output requested with printf(), puts() and putchar() will appear in the output window of the appropriate node. Any output explicitly directed to C's stdout or stderr will appear on the invoking tty (or xterm window), unless redirected by the shell. If either the -o option or the outputfile attribute are provided, each node's output will also be copied to the indicated file.

Most library functions return the integer 0 on success and the integer -1 on failure. The most recent error status is reflected in the global variable cnet_errno. All values of cnet_errno will be instances of the enumerated type CnetError (defined in ). Errors may be reported to standard error with cnet_perror() and their error message string accessed via *cnet_errstr[].

As well as the standard X-windows and XView or Motif default command line arguments, the following defaults may be speci- fied in your $HOME/.Xdefaults file to define and constrain the execution of cnet. Each resource is presented here with its minimum, default and maximum values in parenthesis.

     cnet.x, cnet.y                  (0,100,800)

The starting coordinates of cnet's baseframe.

     cnet.debug                      (False)

Similar to, though may be overridden by, the -d option.

     cnet.mins                       (1,3,(1<<30))

Similar to, though may be overridden by, the -m mins option.

     cnet.random                     (2,unused,100)

Similar to, though may be overridden by, the -r nnodes option.

     cnet.report                     (5,20,1000)

How frequently (in seconds) to report the scheduler's activity iff -d is specified.

     cnet.trace                      (False)

Similar to, though may be overridden by, the -t option.

     cnet.showstats                  (False)

Indicate if cnet's statistics window should be ini- tially displayed.

     cnet.statsx, cnet.statsy        (0,100,800)

The starting coordinates of cnet's statistics window.

EXIT STATUS

cnet will exit with a 0 if either the ``Kill cnet'' button is selected or the time limit expires. Any other condi- tions, such as an error in the topology file or a syntax error in the protocol source files, will result in cnet exiting with a status of 1.

FILES

Some example material appears in /home/kultarr/year3/examples/it312 The standard header file which is included by cnet itself, and should be included in your protocol files, is in /usr/kultarr/lib. The environment variable CNETPATH may define a colon delimited list of directories in which to find an alternate file.

SEE ALSO

[McD91]
"A Network Specification Language and Execution Environment for Undergraduate Teaching", C.S. McDonald, Proc. of the ACM Computer Science Education Technical Symposium '91, San Antonio, Texas, Mar 1991, pp25-34.

[McD93]
"Network Simulation Using User-level Context Switching", C.S. McDonald, Proc. of the Australian UNIX Users' Group Conference '93, Sydney, Sept 1993, pp1-10.

LIMITATIONS

cnet refuses to compile files with the word receive spelt incorrectly.

Only one application layer type and one physical layer type may be specified, with -A and -P respectively. It is not possible for each node to use a different application layer or physical layer.

As cnet uses the X-windows environment under UNIX, the pro- tocols must not use the following UNIX system and library functions: alarm(3), getitimer(3), ioctl(2), setitimer(2), sigblock(2), sigmask(2), signal(3), sigvec(2), system(3), wait(2), wait3(2) or perform any UNIX I/O that may block.

AUTHOR

• Chris McDonald (The University of Western Australia, chris@cs.uwa.edu.au)
• Thanks to:
  • Chris Johnson (cwj@dcs.anu.edu.au)
  • Duncan McEwan (duncan@comp.vuw.ac.nz)
  • Chris Pudney (chrisp@cs.uwa.edu.au).