The cnet network simulator - Physical Layer
Keywords: network simulator simulation protocol undergraduate teaching

### cnet's Physical Layer

The Physical Layer (either the internal default version or one provided with the -R 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.

When your protocols wish to transmit a data frame along a link, they write that frame to the Physical Layer. On calling the `CNET_write_physical` function, you indicate the length of the frame to be written and on return `CNET_write_physical` indicates how many bytes were accepted. A typical sequence for a 2 node network is:

        char myframe[ MAX_MESSAGE_SIZE + MY_OVERHEAD ];
        int  framelength;

         ...   /* prepare frame contents for transmission */
        framelength = ... ;
        result = CNET_write_physical(1, myframe, &framelength);

When cnet informs the destination node that a frame has arrived, the handler for `EV_PHYSICALREADY` should read that frame. On return from a successful call to `CNET_read_physical`, your protocol is informed on which link the frame arrived and how long it was. Of course, in a simple 2 node network all frames will arrive on link number `1`.

        char myframe[8*K];
        int  link, length;

        length = sizeof(myframe);
        result = CNET_read_physical(&link, myframe, &length);
         ...   /* process frame contents */

Two additional Physical Layer functions are provided to assist in the debugging of multi-layered protocols. `CNET_write_physical_reliable` is identical to `CNET_write_physical` except that frames sent using it will not be subject to frame corruption or loss. It can be considered as a ``perfect'' Data Link Layer if you just want to implement higher-layered protocols. The function `CNET_write_direct` also bypasses all Physical Layer errors and instructs a message to be sent directly to the node whose address is specified as a parameter. It thus provides perfect a Data Link Layer and Network Layer.

### 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 special case, a node may reliably transmit a frame to itself by requesting the `LOOPBACK(=0)` link. On invocation, `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.

  Possible errors: `ER_BADARG, ER_BADLINK, ER_BADSIZE, ER_LINKDOWN, ER_NOTREADY, ER_TOOBUSY.`

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

  Identical to `CNET_write_physical` though the transmission is guaranteed to be error free (providing a reliable data-link layer).

  Possible errors: `ER_BADARG, ER_BADLINK, ER_BADSIZE, ER_LINKDOWN, ER_NOTREADY, ER_TOOBUSY.`

`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 transmitted using `CNET_write_direct` are considered to be transmitted on, and arrive on, link number `1`. The special destination address `BROADCAST` may be used to transmit a message to all nodes except the sender.

  Possible errors: `ER_BADARG, ER_BADLINK, ER_BADSIZE, ER_LINKDOWN, ER_NOTREADY, ER_TOOBUSY.`

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

  Possible errors: `ER_BADARG, ER_BADSIZE, ER_CORRUPTDATA, ER_NOTREADY.`

cnet was written and is maintained by Chris McDonald (chris@cs.uwa.edu.au)