cnet (local)UNIX Programmer's Manual cnet(local)
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
-A string
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.
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.
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.
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:
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:
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:
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:
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).
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
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.
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.