cnet v2.0.5

home
introduction
simulation model

topology files
cmdline options
the API

FAQ

download

Drawing data frames in cnet

As of version 1.7, cnet can present a limited visualisation of data frames traversing the Physical Layer via a point-to-point link. Using just colours and lengths, it is possible to display both data and acknowledgment frames, and the contents of some of their fields. In combination, these features may be used to debug implementations of Data Link Layer protocols.

Only networks with 2 nodes connected via a single point-to-point link may display their data frames. When drawn, frames simply move from left-to-right or right-to-left until they reach their destination. If the frame becomes lost, because the link's probframeloss attribute is non-zero, only the frame's silhouette (an all white frame) will reach the destination. If the frame is corrupted because the link's probframecorrupt attribute is non-zero, a lightning bolt appears and only a singed (all grey) frame will reach the destination. Of course, both data and acknowledgment frames may be lost and corrupted.

Below, we see a selective-repeat protocol experiencing frame loss (the upper ghostly white data frame number 5) and frame corruption (the singed grey data frame number 3), while other data and acknowledgment frames are also being exchanged.

As with most activities in cnet, frames are drawn using an event-driven approach. If of interest, the cnet event EV_DRAWFRAME is delivered to the running protocol when cnet needs to know how to draw a frame. cnet has no knowledge of the format of the data frames it is delivering, and so the protocol writer must indicate which colours, field lengths, and strings are to be used to draw each frame. cnet defines the CnetDrawFrame datatype and constants to request colours, such as CN_RED, CN_BLUE, ..., in its standard header file. The colours and lengths (in pixels) of up to 6 fields of each frame may be supplied.

You may also request that a short text string, up to DRAWFRAME_TEXTLEN (=16) bytes in length, be drawn (centred) on each animated frame. cnet will only deliver the EV_DRAWFRAME event to the protocol once per frame, and the protocol is not, itself, responsible for drawing or moving each frame. This enables you to concentrate on writing the protocol, not any visualisation.

line

To request the drawing of data frames in a 2-node network, add the following global Boolean attribute to your topology file:

    drawframes  =  true

Next, inside your protocol's code to receive the EV_REBOOT event, register an event handler to receive the EV_DRAWFRAME event:


void reboot_node(CnetEvent ev, CnetTimer timer, CnetData data) 
{
    .....
    CHECK(CNET_set_handler( EV_DRAWFRAME, draw_frame, 0));
    .....
}

Finally, define an event handler to receive the EV_DRAWFRAME event. cnet passes to the handler, in the CnetData parameter, a pointer to an instance of the CnetDrawFrame datatype. This pointer provides access to colour, pixel (length), and text arrays, as well as a pointer to the data frame to be drawn. Again, cnet does not know the format of the protocol's data frame. In the following example code, the FRAME datatype, and its kind and seq structure fields are known to the protocol, but not to cnet. (If you're unsure of what's happening here, just copy the first few lines this code, verbatim):


void draw_frame(CnetEvent ev, CnetTimer timer, CnetData data)
{
    CnetDrawFrame *df  = (CnetDrawFrame *)data;
    FRAME         *f   = (FRAME *)df->frame;

    if(f->kind == ACK) {
        df->colour[0]  = (f->seq == 0) ? CN_RED : CN_PURPLE;
        df->pixels[0]  = 10;
        sprintf(df->text, "ack=%d", f->seq);
    }
    else if(f->kind == DATA) {
        df->colour[0]  = (f->seq == 0) ? CN_RED : CN_PURPLE;
        df->pixels[0]  = 10;
        df->colour[1]  = CN_GREEN;
        df->pixels[1]  = 30;
        sprintf(df->text, "data=%d", f->seq);
    }
}

This example code will draw each acknowledgment frame with 1 field, 10 pixels long, and each data frame with 2 fields, totalling 40 pixels long. Frames with a sequence number of 0 will have their first field drawn in red; other sequence numbers will be represented with purple. Data frames will have a second field, representing their payload, drawn in green. Both types of frames also request that a short text string, displaying their sequence number, be drawn (centred) on their animated frames

RESTRICTIONS:

For best results, simulations drawing drames should run slowly. Because the protocol writer has control over the length (size) of the frames drawn, it is possible for frames moving in the same direction to be drawn on top of one another (although they will not overtake one another!). Clearly this doesn't represent reality too well. The following conditions provide a reasonable representation:

    drawframes       = true
    messagerate      = 1000ms
    propagationdelay = 1500ms

Data frames are only displayed under the following conditions:

  • the global Boolean attribute drawframes is set to true in the topology file.
  • the network has only 2 nodes connected via a single point-to-point link, and
  • the -T and -W command-line options are not used.
cnet was written and is maintained by Chris McDonald (chris@csse.uwa.edu.au)