Documentation/filesystems/fat_cvf.txt

   1 This is the main documentation for the CVF-FAT filesystem extension.  18Nov1998
   2
   3
   4 Table of Contents:
   5
   6 1. The idea of CVF-FAT
   7 2. Restrictions
   8 3. Mount options
   9 4. Description of the CVF-FAT interface
  10 5. CVF Modules
  11
  12 ------------------------------------------------------------------------------
  13
  14
  15 1. The idea of CVF-FAT
  16 ------------------------------------------------------------------------------
  17
  18 CVF-FAT is a FAT filesystem extension that provides a generic interface for
  19 Compressed Volume Files in FAT partitions. Popular CVF software, for
  20 example, are Microsoft's Doublespace/Drivespace and Stac's Stacker.
  21 Using the CVF-FAT interface, it is possible to load a module that handles
  22 all the low-level disk access that has to do with on-the-fly compression
  23 and decompression. Any other part of FAT filesystem access is still handled
  24 by the FAT, MSDOS or VFAT or even UMSDOS driver.
  25
  26 CVF access works by redirecting certain low-level routines from the FAT
  27 driver to a loadable, CVF-format specific module. This module must fake
  28 a normal FAT filesystem to the FAT driver while doing all the extra stuff
  29 like compression and decompression silently.
  30
  31
  32 2. Restrictions
  33 ------------------------------------------------------------------------------
  34
  35 - BMAP problems
  36
  37   CVF filesystems cannot do bmap. It's impossible in principle. Thus
  38   all actions that require bmap do not work (swapping, writable mmapping).
  39   Read-only mmapping works because the FAT driver has a hack for this
  40   situation :) Well, writable mmapping should now work using the readpage
  41   interface function which has been hacked into the FAT driver just for
  42   CVF-FAT :)
  43
  44 - attention, DOSEmu users
  45
  46   You may have to unmount all CVF partitions before running DOSEmu depending
  47   on your configuration. If DOSEmu is configured to use wholedisk or
  48   partition access (this is often the case to let DOSEmu access
  49   compressed partitions) there's a risk of destroying your compressed
  50   partitions or crashing your system because of confused drivers.
  51
  52   Note that it is always safe to redirect the compressed partitions with
  53   lredir or emufs.sys. Refer to the DOSEmu documentation for details.
  54
  55
  56 3. Mount options
  57 ------------------------------------------------------------------------------
  58
  59 The CVF-FAT extension currently adds the following options to the FAT
  60 driver's standard options:
  61
  62   cvf_format=xxx
  63     Forces the driver to use the CVF module "xxx" instead of auto-detection.
  64     Without this option, the CVF-FAT interface asks all currently loaded
  65     CVF modules whether they recognize the CVF. Therefore, this option is
  66     only necessary if the CVF format is not recognized correctly
  67     because of bugs or incompatibilities in the CVF modules. (It skips
  68     the detect_cvf call.) "xxx" may be the text "none" (without the quotes)
  69     to inhibit using any of the loaded CVF modules, just in case a CVF
  70     module insists on mounting plain FAT filesystems by misunderstanding.
  71     "xxx" may also be the text "autoload", which has a special meaning for
  72     a module loader, but does not skip auto-detection.
  73
  74     If the kernel supports kmod, the cvf_format=xxx option also controls
  75     on-demand CVF module loading. Without this option, nothing is loaded
  76     on demand. With cvf_format=xxx, a module "xxx" is requested automatically
  77     before mounting the compressed filesystem (unless "xxx" is "none"). In
  78     case there is a difference between the CVF format name and the module
  79     name, setup aliases in your modules configuration. If the string "xxx"
  80     is "autoload", a non-existent module "cvf_autoload" is requested which
  81     can be used together with a special modules configuration (alias and
  82     pre-install statements) in order to load more than one CVF module, let
  83     them detect automatically which kind of CVF is to be mounted, and only
  84     keep the "right" module in memory. For examples please refer to the
  85     dmsdos documentation (ftp and http addresses see below).
  86
  87   cvf_options=yyy
  88     Option string passed to the CVF module. I.e. only the "yyy" is passed
  89     (without the quotes). The documentation for each CVF module should
  90     explain it since it is interpreted only by the CVF module. Note that
  91     the string must not contain a comma (",") - this would lead to
  92     misinterpretation by the FAT driver, which would recognize the text
  93     after a comma as a FAT driver option and might get confused or print
  94     strange error messages. The documentation for the CVF module should
  95     offer a different separation symbol, for example the dot "." or the
  96     plus sign "+", which is only valid inside the string "yyy".
  97
  98
  99 4. Description of the CVF-FAT interface
 100 ------------------------------------------------------------------------------
 101
 102 Assuming you want to write your own CVF module, you need to write a lot of
 103 interface functions. Most of them are covered in the kernel documentation
 104 you can find on the net, and thus won't be described here. They have been
 105 marked with "[...]" :-) Take a look at include/linux/fat_cvf.h.
 106
 107 struct cvf_format
 108 { int cvf_version;
 109   char* cvf_version_text;
 110   unsigned long int flags;
 111   int (*detect_cvf) (struct super_block*sb);
 112   int (*mount_cvf) (struct super_block*sb,char*options);
 113   int (*unmount_cvf) (struct super_block*sb);
 114   [...]
 115   void (*zero_out_cluster) (struct inode*, int clusternr);
 116 }
 117
 118 This structure defines the capabilities of a CVF module. It must be filled
 119 out completely by a CVF module. Consider it as a kind of form that is used
 120 to introduce the module to the FAT/CVF-FAT driver.
 121
 122 It contains...
 123   - cvf_version:
 124       A version id which must be unique. Choose one.
 125   - cvf_version_text:
 126       A human readable version string that should be one short word
 127       describing the CVF format the module implements. This text is used
 128       for the cvf_format option. This name must also be unique.
 129   - flags:
 130       Bit coded flags, currently only used for a readpage/mmap hack that
 131       provides both mmap and readpage functionality. If CVF_USE_READPAGE
 132       is set, mmap is set to generic_file_mmap and readpage is caught
 133       and redirected to the cvf_readpage function. If it is not set,
 134       readpage is set to generic_readpage and mmap is caught and redirected
 135       to cvf_mmap. (If you want writable mmap use the readpage interface.)
 136   - detect_cvf:
 137       A function that is called to decide whether the filesystem is a CVF of
 138       the type the module supports. The detect_cvf function must return 0
 139       for "NO, I DON'T KNOW THIS GARBAGE" or anything >0 for "YES, THIS IS
 140       THE KIND OF CVF I SUPPORT". The function must maintain the module
 141       usage counters for safety, i.e. do MOD_INC_USE_COUNT at the beginning
 142       and MOD_DEC_USE_COUNT at the end. The function *must not* assume that
 143       successful recognition would lead to a call of the mount_cvf function
 144       later.
 145   - mount_cvf:
 146       A function that sets up some values or initializes something additional
 147       to what has to be done when a CVF is mounted. This is called at the
 148       end of fat_read_super and must return 0 on success. Definitely, this
 149       function must increment the module usage counter by MOD_INC_USE_COUNT.
 150       This mount_cvf function is also responsible for interpreting a CVF
 151       module specific option string (the "yyy" from the FAT mount option
 152       "cvf_options=yyy") which cannot contain a comma (use for example the
 153       dot "." as option separator symbol).
 154   - unmount_cvf:
 155       A function that is called when the filesystem is unmounted. Most likely
 156       it only frees up some memory and calls MOD_DEC_USE_COUNT. The return
 157       value might be ignored (it currently is ignored).
 158   - [...]:
 159       All other interface functions are "caught" FAT driver functions, i.e.
 160       are executed by the FAT driver *instead* of the original FAT driver
 161       functions. NULL means use the original FAT driver functions instead.
 162       If you really want "no action", write a function that does nothing and
 163       hang it in instead.
 164   - zero_out_cluster:
 165       The zero_out_cluster function is called when the fat driver wants to
 166       zero out a (new) cluster. This is important for directories (mkdir).
 167       If it is NULL, the FAT driver defaults to overwriting the whole
 168       cluster with zeros. Note that clusternr is absolute, not relative
 169       to the provided inode.
 170
 171 Notes:
 172   1. The cvf_bmap function should be ignored. It really should never
 173      get called from somewhere. I recommend redirecting it to a panic
 174      or fatal error message so bugs show up immediately.
 175   2. The cvf_writepage function is ignored. This is because the fat
 176      driver doesn't support it. This might change in future. I recommend
 177      setting it to NULL (i.e use default).
 178
 179 int register_cvf_format(struct cvf_format*cvf_format);
 180   If you have just set up a variable containing the above structure,
 181   call this function to introduce your CVF format to the FAT/CVF-FAT
 182   driver. This is usually done in init_module. Be sure to check the
 183   return value. Zero means success, everything else causes a kernel
 184   message printed in the syslog describing the error that occurred.
 185   Typical errors are:
 186     - a module with the same version id is already registered or
 187     - too many CVF formats. Hack fs/fat/cvf.c if you need more.
 188
 189 int unregister_cvf_format(struct cvf_format*cvf_format);
 190   This is usually called in cleanup_module. Return value =0 means
 191   success. An error only occurs if you try to unregister a CVF format
 192   that has not been previously registered. The code uses the version id
 193   to distinguish the modules, so be sure to keep it unique.
 194
 195 5. CVF Modules
 196 ------------------------------------------------------------------------------
 197
 198 Refer to the dmsdos module (the successor of the dmsdos filesystem) for a
 199 sample implementation.  It can currently be found at
 200
 201   ftp://fb9nt.uni-duisburg.de/pub/linux/dmsdos/dmsdos-x.y.z.tgz
 202   ftp://sunsite.unc.edu/pub/Linux/system/Filesystems/dosfs/dmsdos-x.y.z.tgz
 203   ftp://ftp.uni-stuttgart.de/pub/systems/linux/local/system/dmsdos-x.y.z.tgz
 204
 205 (where x.y.z is to be replaced with the actual version number). Full
 206 documentation about dmsdos is included in the dmsdos package, but can also
 207 be found at
 208
 209   http://fb9nt.uni-duisburg.de/mitarbeiter/gockel/software/dmsdos/index.html
 210   http://www.yk.rim.or.jp/~takafumi/dmsdos/index.html (in Japanese).