
  Writing File System Plugins for Askant
  --------------------------------------

0. Contents

  1. Intro
  2. API
  3. Reference


1. Intro

In order to gather file system data with which to enhance the data provided by
blktrace, there must be specific code written for each file system type we wish
to support. This is where file system plugins come along. The plugins must
basically traverse an on-disk file system structure on a block device and report
back their findings through a callback handed to them by askant. They must also
expose a function which stops their traversal loop in case askant wishes to stop
their execution prematurely.


2. API

A file system plugin must be written as a Python module. This means that C, C++
and Python are suitable languages to write them in. They must expose a number of
Python functions to askant:

parsefs(dev)
    
    This function is called when askant wants the plugin to parse the file
    system on the device specified by the device, dev.

get_block_size()

    This function is called to ascertain the file system block size which is
    required in order to map the disk sector numbers provided by blktrace to
    file system block numbers. It takes no arguments and should return a Python
    integer value.

set_report_hook(func)

    This function is called to pass in a report function which the plugin should
    call to report the details of a file system block. func is a function which
    accepts four arguments in this order:
    
    Block number: a Python long integer
    Block type: a Python string
    Block number of parent: a Python long integer
    Block file name: a Python string (should be "" for non-inode blocks)

handle_sigint()

    This function should make the plugin stop its parsing loop. This allows it
    to be interrupted if askant catches a signal, for example. It takes no
    arguments and its return value is not used.


3. Reference

o See fsplugins/gfs2/gfs2module.c for an example of writing a Python fs plugin
  module in C.

o http://www.python.org/doc/ext/intro.html shows how to extend Python with C or
  C++.
