# The dd_rescue plugin interface
dd_rescue supports plugins. These can analyze and transform data. Current
examples are a ddr_hash plugin (analyzing the data only), ddr_crypt (doing AES
en/decryption) and ddr_lzo and ddr_lzma plugins which do (de)compression.
## The interface specification.
Any plugin comes with a declaration of how it operates with ddr_plugin_t
structure.
It contains a name, a few settings and flags and a few callbacks.
The following description will describe the flow and use this to explain the
flags ...
## Initialization phase
User calls dd_rescue -L XXXX=parameters1[,YYYY=parameters2] [options] in out
dd_rescue on initializations loads all plugins from left to right. It uses
dlopen to open libddr_XXXX.so. If XXXX is a full path (detected by finding a /
in the name), the path will be loaded by dlopen instead. All plugins are kept
in a linked list.
The ddr_plugin_t structure is found by searching for the ddr_plug symbol.
The initialization fills in the logger structure, which the plugin can use to
send log messages. If non-null, the init_callback will be called with the
parameters and a sequence number communicating where in the food chain the
plugin is. This init_callback is supposed to support a parameter help and
output usage instructions in return. (Output should be created using the
FPLOG() macro with INFO severity.)
The init_callback should do all the parameter analysis, allocate internal
storage etc. Note that no files have been opened yet when this happens. The
dd_rescue options have been parsed already at this point and can be analyzed or
stored if needed.
The ddr_plugin_t structure has a void pointer state meant to keep internal
state. It's passed to all callbacks.
Please see the ddr_plugin.h file for detailed interface declarations.
The deinitialization happens with the release_callback which should free any
storage allocated in init.
The overall lifecycle is:
init_callback -> open_callback
-> block_callback [mnay times]
-> close_callback
-> release_callback
## Open and Close
Once the input and output files have been opened and the file positions been
initialized, the open_callback is called. There are a few flags passed related
to buffer handling, see below. The plugin can return a negative return code,
signaling the main process to abort.
The close_callback is called before input and output files are closed.
Flushing any buffers however should have been done before, so this is often a
no-op. Returning non-zero will be counted and reported as exit code from
dd_rescue.
## Processing the blocks
dd_rescue reads blocks of data. Before writing the blocks out again, it
calls all plugins' block_callback one after the other.
Each plugin can process the buffer, optionally do adjustments to positions (in
the file position struct) and pass back a modified or unmodified buffer that
then gets passed on to the next plugin and ultimately to dd_rescue's output
routine. The length ot output data (in *towr) can also be adjusted as needed.
Plugins have a lot of freedom, which also makes it hard to guarantee
correctness in all cases, where dd_rescue jumps around, e.g. due to repeated
attempts to read hard-to-read data, jumping over unreadable blocks or jumping
over zeroed blocks or doing reverse direction copies. Plugins need to detect
these things (by looking at the file position struct) or indicate via flags
that they are not supporting certain modes of operation. See buffer handling
section below.
Fatal errors are reported by an FPLOG(FATAL) message and raise(SIGQUIT) which
will make dd_rescue abort the copy process and exit gracefully.
The block_callback gets called once with eof=1 at the end, telling the plugin
to flush buffers etc, so the regular dd_rescue write path can process the final
bytes of the data produced this way.
## Buffer handling
In the easiest case, the plugin does not change the length of the buffer; if it
can transform data in place (or not transform it at all), it can just return
a pointer to the original buffer. Some plugins require a few bytes in front or
behind the buffer but otherwise can deal without creating a block sized own
buffer; this is indicated by slack_pre and slack_post; please see the comments
in the struct to see how to state it in terms of block sizes.
dd_rescue will collect all needs from the plugins and allocated an accordingly
larger buffer that's passed along. The open_callback will pass on this
information in case plugins do their own memory allocation and need to
accomodate surrounding plugins. The needs_align will also be considered by
dd_rescue's buffer allocation.
In the open_callback, the plugin will also be informed if plugins earlier or
later in the chain do change the contents and the length of the data.
## Non-linear motion
dd_rescue might jump around; in particular it might jump over unreadable or
zeroed (sparse detection) blocks or do a reverse direction copy.
Plugins will need to detect this; typically by remembering the previous
position and then doing whatever is needed for correct operation on a
forward jump (assuming all jumped-over contents is zeroes).
Plugins can indicate to not support sparse operation if they need to avoid
the complexity of getting this right. Otherwise, the plugins hash, crypt,
lzo all support rather complex cases.