The ONL NPR Tutorial

NPR Tutorial >> Router Plugins

TOC

Sending A Message To A Plugin

Introduction

Most useful plugins respond to control messages. Some control messages provide feedback to the user (GET) while others allow the user to set plugin variable values (SET). For example, most plugins have a counter that indicates the number of packets seen by the plugin. The plugin developer usually provides one control message for retrieving that counter value and another for resetting the counter. As an example, the delay plugin has four visible counters: npkts (number of packets seen), maxinq (maximum number of packets in the delay queue), ndrops (number of packet drops from queue overflow), and ninq (number of packets in the delay queue). But some plugins allow the user to change the behavior of the plugin by setting control variables. For example, the delay plugin normally delays packets by 50 msec, but a user can change that delay through the control message interface.

We have already seen how to install a plugin through a plugin control window. This same window can be used to send messages to a specific plugin through the Edit => Send Command to Plugin menu item. This page describes how messages get to and from a plugin and illustrates how to send messges to a plugin:

• Plugin Message Architecture
• Delay Plugin Example

This section describes the architecture of the plugin message system by following a control message as it makes its way from the RLI to the Xscale processor and then to the plugin which sends a reply message is back to the RLI.

The figure (right) shows the =counts control message as it is created by the user in the Send Command to Plugin window. The message enterred in the message window is sent unedited to the target plugin. You should realize the following about the message you enter:

• You can not enter more than 28 characters (including spaces).

  This is usually not an issue since most commands are much shorter than 28 characters. But since spaces are sent as enterred, you should not be so cavalier as to think that you can send an arbitrary number of spaces.

• A plugin receiving a message expects the message to be a sequence of white-space separated words.

  Typically, a plugin will convert numeric words to their internal form. For example, the delay plugin message "delay= 25" sets the delay to 25 msec. The word "25" is passed in ASCII form to the plugin where it is converted to a 32-bit integer.

• There is no standard input message format except that all plugins to-date assume that the first word is a command or operation name (e.g., =counts) and that 0 or more words corresponding to command arguments follow the command. The number of arguments is plugin dependent.

  NPR Tutorial => Router Plugins => Predefined Plugins document the command formats for predefined (or standard) plugins. By convention, plugin writers are expected to supply a README file for each plugin that documents the control messages. The README files for predefined plugins are located in the standard plugin source code subdirectories located at ~onl/npr/plugins/ (e.g., ~onl/npr/plugins/delay/README for the delay plugin).

Shown in the figure (above) is the path (shown in red) taken by a request message from the RLI to plugin 0 through the Xscale and the returning reply message which takes the reverse path. The RLI tranmsits the plugin message to a control daemon running on the Xscale processor of the target NPR. The control daemon forms an internal message consisting of a 4-byte (32-bit) header followed by the 28-byte user message and puts the message into the SRAM message queue of the target plugin (plugin0 in this example). The figure also shows that these message queues are 512 words (one word is 32 bits). A simple calculation shows that a message queue can hold atmost 16 messages; i.e., these message queues are small when compared with the meta-packet queues which are 64K words each.

Meanwhile one thread of each plugin is typically blocked in its handle_msg routine waiting for a control message to arrive to its message queue. When the message handling thread is given control of the ME, it wakes up and processes the control message and sends back a reply. The outgoing reply message has the same format as the incoming request message (one word header followed by a 7-word message body). By convention, the body of the reply message is an ASCII C-string. This means that if a plugin wants to return one or more integer values, it converts the value from internal representation to a string before putting the reply message in its reply queue.

A plugin inserts the reply message into its reply message queue. Eventually, a control daemon running on the Xscale processor of the plugin's NPR reads the reply message and sends it to the RLI where it is displayed in the Command Log window.

Each plugin understands a specific set of commands. We use the delay plugin as an example and illustrate how to get counter values, reset counters, and set the delay to 25 msec. A more detailed example is given in the example page NPR Tutorial => Examples => TCP With Delay and specifically in these two subsections: Install a delay plugin and Get counts from the delay plugin.

Here is a list of the most useful delay plugin commands that can be enterred in an RLI plugin message window:

Our intent here is not to describe the delay plugin in detail but to illustrate the concept of a plugin control message. More details about the delay plugin in particular and predefined plugins in general are described later in NPR Tutorial => Router Plugins => Predefined Plugins and summarized in NPR Tutorial => Summary Information => Predefined Plugins.

CAVEAT: At this point, you might think that there is a standard format for control messages because the table above seems to indicate that GET operations begin with '=' and SET operations end with '='. As of this writing, there is no such standard or convention applied to all plugins. Only the delay plugin uses this convention.

In the example below, we assume that the delay plugin has been installed in microengine (ME) 0 of NPR 2. Furthermore, the screen shots are for the case where TCP packets go through a path with the following characteristics:

• 10 Mbps bottleneck
• 50 msec delay

1. Read the main delay plugin counters

• Plugin Window:
  Select Edit => Send Command to Plugin

A Send Comamnd window appears allowing you to enter a plugin command.

• Send Command Window:
  Enter 0 in the microengine box; Enter =counts in the message box; and Select Enter.




The =counts command reads the three main packet counters:

• npkts: Total number of packets seen by the plugin
• maxinq: The maximum number of packets in the delay queue
• ndrops: The number of packets dropped by the plugin


• Plugin Command Log Window: A message shows that the three counter values are npkts = 82008, maxinq = 43, and ndrops = 0.
  



Note: It is interesting that the value of maxinq is 43; i.e., at some point the plugin had 43 packets in its queue. A simple calculation will show that the bandwidth-delay product (BDP) for our example is about 42 packets (= 10 Mbps x 50 msec / 12 Kbits/pkt). This is no coincident since the delay queue represents the packet pipeline associated with the 50 msec of delay.

2. Reset the counters

   Suppose we want to repeat the TCP experiment but with a 25 msec delay instead of 50 msec. Before doing so, we would like to reset the delay plugin counters and then verify that the counters have been zeroed.
   We follow the same procedure for the =counts command above but instead send the reset command first.


• Send Command Window:
  Enter 0 in the microengine box; Enter reset in the message box; and Select Enter.


• Send Command Window:
  Enter =counts in the message box; and Select Enter.

The figure shows the output from these two commands with the last one showing that the three main counter values have been zeroed.



3. Change the delay from 50 msec to 25 msec

   Note: The convention followed by the delay plugin for command names is that commands that read from plugin variables begin with the equal character (e.g., =delay, =counts). While those that write to plugin variables end with the equal character (e.g., delay=).

• Send Command Window:
  Enter 0 in the microengine box; Enter delay= 25 in the message box; and Select Enter.
  

Watch Out!!! There must be atleast one space after the equal sign.



• If we start another TCP flow and then read the counters, we should see the effect of reducing the delay by one-half on the maxinq counter.
• Send Command Window:
  Enter 0 in the microengine box; Enter =counts 25 in the message box; and Select Enter.



The figure showing the Plugin Command Log Window shows in the last two lines that the plugin delay was set to 25 msec. Furthermore, it shows that the value of maxinq is 23 which is a little more than one-half of its previous value of 43 when the delay was 50 msec.

NPR Tutorial >> Router Plugins	TOC