bufdump - A utility for dumping NSCL event buffers
Prev	Chapter 6. Extending bufdump	Next

6.2. Writing formatting plugins for the bufdump program.

The internal structure of a packet is not known to bufdump. By default, therefore, bufdump dumps the body of a packet as a sequence of hexadecimal 16 bit words. Plugins are a mechanism that bufdump provides to teach it how to format the internals of a packet.

A plugin is a Tcl procedure that is associated with a particular packet type. When bufdump encounters a packet whose type is known, either through a packet definition file (standard or user provided), or through analysis of a documentation buffer, it checks to see if a plugin has been registered for that packet type. If so, bufdump hands the body of the packet off to that plugin and receives the formatted body in return.

Let's look at a very simple plugin:

    # Plugin to format 0x8000 packets:
    #
    proc format8000 body {   
        set result "Hex   Decimal   Octal\n"
        foreach item $body { 
        append result [format "0x%04x %05d %06o\n" $item $item $item]
    }
    return $result           
    }
    registerPacketFormatter 0x8000 format8000

The procedure format8000 is the plugin procedure. We have adopted the convention that the procedure name will be of the form formatid where id is the hexadecimal id of the packet type this plugin serves. The parameter body will contain the body of the packet when the plugin is called by bufdump. body is a properly formatted Tcl list of numbers. The size of the body can be determined by applying the Tcl llength command to that list.

After initializing the variable result with a header, this foreach loop iterates over each element of the body list appending the hexadecimal, decimal and octal rendition of each body word to the result followed by a newline. Note that all formatting must be explicitly provided by the plugin. At this point in time, there is no support for font selection or other forms of highlighting

The return value from the plugin procedure is the string that will be placed verbatim, without interpretation in bufdump's formatted output.

The registerPacketFormatter command registers the plugin to process packets with an id of 0x8000. The parameters of the registerPacketFormatter are in order:

id: The id of the packet that will be processed by the plugin. This can be any numerical representation of the id that is acceptable to Tcl.
plugin: The procedure to invoke when the id packet is encountered.

We can see from this example that the incorporation of a plugin is a three step process:

Write a plugin procedure that accepts the body of the packet as a parameter and produces as a result the desired formatted representation of the body.
In the same file as the plugin, register the plugin procedure by invoking registerPacketFormatter. The call to registerPacketFormatter must supply the packet id as well as the name of the procedure you wrote in the previous step.
Users of bufdump invoke the: File->Add Plugin... menu command and select the file that provides the plugin.

A cautionary word about plugin distribution. A plugin, like any other program may have defects that you will repair over the life-cycle of the plugin. We recommend against the distribution of copies of plugins within a single institution. Plugins should be installed in some centralized repository and users should be encouraged to add them from the repository so that at any given time, they will receive the most up-to-date versions.

Finally, this plugin interface is primitive. If you have suggestions for enhancing this interface, please feel free to maek them via the NSCL bugzilla web pages.