patch-2.1.79 linux/Documentation/filesystems/fat_cvf.txt

• Lines: 191
• Date: Thu Jan 8 14:02:41 1998
• Orig file: v2.1.78/linux/Documentation/filesystems/fat_cvf.txt
• Orig date: Wed Dec 31 16:00:00 1969

diff -u --recursive --new-file v2.1.78/linux/Documentation/filesystems/fat_cvf.txt linux/Documentation/filesystems/fat_cvf.txt
@@ -0,0 +1,190 @@
+This is the main documentation for the CVF-FAT filesystem extension.  31DEC1997
+
+
+Table of Contents:
+
+1. The idea of CVF-FAT
+2. Restrictions
+3. Mount options
+4. Description of the CVF-FAT interface
+5. CVF Modules
+
+------------------------------------------------------------------------------
+
+
+1. The idea of CVF-FAT
+------------------------------------------------------------------------------
+
+CVF-FAT is a FAT filesystem extension that provides a generic interface for
+Compressed Volume Files in FAT partitions. Popular CVF software, for
+example, are Microsoft's Doublespace/Drivespace and Stac's Stacker.
+Using the CVF-FAT interface, it is possible to load a module that handles
+all the low-level disk access that has to do with on-the-fly compression
+and decompression. All other part of FAT filesystem access is still handled
+by the FAT, MSDOS or VFAT or even UMSDOS driver.
+
+CVF access works by redirecting certain low-level routines from the FAT
+driver to a loadable, CVF-format specific module. This module must fake
+a normal FAT filesystem to the FAT driver while doing all the extra stuff
+like compression and decompression silently.
+
+
+2. Restrictions
+------------------------------------------------------------------------------
+
+- BMAP problems
+
+  CVF filesystems cannot do bmap. It's impossible by principle. Thus
+  all actions that require bmap do not work (swapping, writable mmapping).
+  Read-only mmapping works because the FAT driver has a hack for this
+  situation :) Well, with some tricks writable mmapping could work,
+  (proof: they did under old dmsdos), but..... (hint: readpage/writepage
+  interface functions) ...... but the FAT driver has to support them 
+  first without bmap :-)
+
+  We'll see. If someone points me to an application that needs this, I
+  might be persuaded to implement it :). CVF-FAT is already prepared
+  for using readpage.
+  
+- DOSEMU users attention 
+
+  You may have to unmount all CVF partitions before running DOSEMU depending 
+  on your configuration. If DOSEMU is configured to use wholedisk or 
+  partition access (this is often the case to let DOSEMU access 
+  compressed partitions) there's a risk of destroying your compressed 
+  partitions or crashing your system because of confused drivers.
+  
+  Note that it is always safe to redirect the compressed partitions with 
+  lredir or emufs.sys. Refer to the DOSEMU documentation for details.
+
+
+3. Mount options
+------------------------------------------------------------------------------
+
+The CVF-FAT extension currently adds the following options to the FAT
+driver's standard options:
+
+  cvf_format=xxx
+    Forces the driver to use the CVF module "xxx" instead of auto-detection.
+    This is only necessary if the CVF format is not recognized corrrectly
+    because of bugs or incompatibilities in the CVF modules. (It skips
+    the detect_cvf call.) "xxx" may be the text "none" (without the quotes)
+    to inhibit using any of the loaded CVF modules, just in case a CVF
+    module insists on mounting plain FAT filesystems by misunderstanding :)
+
+  cvf_options=yyy
+    Option string passed to the CVF module. I.e. only the "yyy" is passed
+    (without the quotes). The documentation for each CVF module should 
+    explain it since it is interpreted only by the CVF module. Note that 
+    the string must not contain a comma (",") - this would lead to 
+    misinterpretation by the FAT driver, which would recognize the text 
+    after a comma as a FAT driver option and might get confused or print 
+    strange error messages. The documentation for the CVF module should 
+    offer a different seperation symbol, for example the dot ".", which
+    is only valid inside the string "yyy".
+
+
+4. Description of the CVF-FAT interface
+------------------------------------------------------------------------------
+
+Assuming you want to write your own CVF module, you need to write a lot of
+interface funtions. Most of them are covered in the kernel documentation
+you can find on the net, and thus won't be described here. They have been
+marked with "[...]" :-) Take a look at include/linux/fat_cvf.h.
+
+struct cvf_format
+{ int cvf_version;
+  char* cvf_version_text;
+  unsigned long int flags;
+  int (*detect_cvf) (struct super_block*sb);
+  int (*mount_cvf) (struct super_block*sb,char*options);
+  int (*unmount_cvf) (struct super_block*sb);
+  [...]
+  void (*cvf_zero_cluster) (struct inode*inode,int clusternr);
+}
+
+This structure defines the capabilities of a CVF module. It must be filled
+out completely by a CVF module. Consider it as a kind of form that is used
+to introduce the module to the FAT/CVF-FAT driver.
+
+It contains...
+  - cvf_version:
+      A version id which must be uniqe. Choose one.
+  - cvf_version_text:
+      A human readable version string that should be one short word 
+      describing the CVF format the module implements. This text is used
+      for the cvf_format option. This name must also be uniqe.
+  - flags:
+      Bit coded flags, currently only used for a readpage/mmap hack that 
+      provides both mmap and readpage functionality. If CVF_USE_READPAGE
+      is set, mmap is set to generic_file_mmap and readpage is caught
+      and redirected to the cvf_readpage function. If it is not set,
+      readpage is set to generic_readpage and mmap is caught and redirected
+      to cvf_mmap.
+  - detect_cvf:
+      A function that is called to decide whether the filesystem is a CVF of
+      the type the module supports. The detect_cvf function must return 0
+      for "NO, I DON'T KNOW THIS GARBAGE" or anything !=0 for "YES, THIS IS
+      THE KIND OF CVF I SUPPORT". The function must maintain the module
+      usage counters for safety, i.e. do MOD_INC_USE_COUNT at the beginning
+      and MOD_DEC_USE_COUNT at the end. The function *must not* assume that
+      successful recongition would lead to a call of the mount_cvf function
+      later. 
+  - mount_cvf:
+      A function that sets up some values or initializes something additional
+      to what has to be done when a CVF is mounted. This is called at the
+      end of fat_read_super and must return 0 on success. Definitely, this
+      function must increment the module usage counter by MOD_INC_USE_COUNT.
+      This mount_cvf function is also responsible for interpreting a CVF
+      module specific option string (the "yyy" from the FAT mount option
+      "cvf_options=yyy") which cannot contain a comma (use for example the
+      dot "." as option separator symbol).
+  - unmount_cvf:
+      A function that is called when the filesystem is unmounted. Most likely
+      it only frees up some memory and calls MOD_DEC_USE_COUNT. The return
+      value might be ignored (it currently is ignored).
+  - [...]:
+      All other interface functions are "caught" FAT driver functions, i.e.
+      are executed by the FAT driver *instead* of the original FAT driver
+      functions. NULL means use the original FAT driver functions instead.
+      If you really want "no action", write a function that does nothing and 
+      hang it in instead.
+  - cvf_zero_cluster:
+      The cvf_zero_cluster function is called when the fat driver wants to
+      zero out a (new) cluster. This is important for directories (mkdir).
+      If it is NULL, the FAT driver defaults to overwriting the whole
+      cluster with zeros. Note that clusternr is absolute, not relative
+      to the provided inode.
+
+Notes:
+  1. The cvf_bmap function should be ignored. It really should never
+     get called from somewhere. I recommend redirecting it to a panic
+     or fatal error message so bugs show up immediately.
+  2. The cvf_writepage function is ignored. This is because the fat
+     driver doesn't support it. This might change in future. I recommend
+     setting it to NULL (i.e use default).
+
+int register_cvf_format(struct cvf_format*cvf_format);
+  If you have just set up a variable containing the above structure,
+  call this function to introduce your CVF format to the FAT/CVF-FAT
+  driver. This is usually done in init_module. Be sure to check the
+  return value. Zero means success, everything else causes a kernel
+  message printed in the syslog describing the error that occured.
+  Typical errors are:
+    - a module with the same version id is already registered or 
+    - too many CVF formats. Hack fs/fat/cvf.c if you need more.
+
+int unregister_cvf_format(struct cvf_format*cvf_format);
+  This is usually called in cleanup_module. Return value =0 means
+  success. An error only occurs if you try to unregister a CVF format
+  that has not been previously registered. The code uses the version id
+  to distinguish the modules, so be sure to keep it uniqe.
+
+5. CVS Modules
+------------------------------------------------------------------------------
+
+Refer to the dmsdos module (the successor of the dmsdos filesystem) for a
+sample implementation.  It can currently be found at
+
+  ftp://fb9nt.uni-duisburg.de/pub/linux/dmsdos
+